企业官网建设流程全解析

1. Django 项目接入 AI 能力时，为什么总在 settings 和调用层卡住

很多 Django 后端项目在接入 AI 能力时，第一反应是直接在视图函数里写一段requests.post，把 API Key 硬编码进去，跑通一次就提交了。等到第二个接口也要用、第三个模块也要用的时候，问题就来了：Key 散落在五六个文件里，换一次 Key 要全局搜索替换；超时、重试、错误处理各写各的；测试环境不小心打到生产 Key；日志里把 Key 明文打出来了。这些坑我在实际项目里都踩过，最后不得不回头做一次重构。

这篇要解决的问题很具体：在不改变原有 Django/DRF 工作流的前提下，把 AI 调用收敛成一个可复用的服务层，Key 从 settings 统一读取，视图层只负责业务逻辑。适合已经有一个能跑的 Django 项目、想加一个「AI 摘要」「AI 分类」「AI 问答」之类接口的后端开发者。你不需要推翻现有的 models、serializers、views 结构，只需要新增一个 service 模块和几行配置。

核心检索词先明确：Django 接入 AI 统一 Key 管理，指的是把大模型调用的凭证、Base URL、模型 ID 集中到 Django settings，通过一个封装好的 client 服务层对外提供能力，让 DRF 视图像调用普通 Python 函数一样调用 AI。这样做的好处是配置可切换、调用可测试、错误可追踪。

整篇的路线是：先讲清楚工程化落地的分层思路，再给出 TaoToken 的配置前置，然后是可复制的 settings 片段和服务层封装代码，接着用 curl 和 Django shell 双重验证一次端到端调用，最后把常见的 401、超时、返回结构解析错误逐个排查掉。全程围绕 Django 的目录结构展开，代码可以直接贴进你的项目。

2. TaoToken 前置准备：统一 Key 与 Base URL 的获取

在写代码之前，需要先拿到调用凭证。TaoToken 提供的是 OpenAI 兼容风格的接口，也就是说你的 Django 服务层可以用标准的chat/completions请求格式，不需要为不同模型写不同的适配代码。这一点对后端工程化很关键，因为接口格式统一意味着服务层只需要维护一套请求逻辑。

先访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录，然后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，进去之后找到 API Keys 管理页面，新建一个 Key。建议按项目或环境命名，比如django-dev、django-prod，这样后面排查问题时能一眼看出是哪个环境在用。

创建完成后你会得到一串以sk-开头的 Key。这里有个习惯要养成：Key 只显示一次，复制后立刻存到环境变量或密码管理器，不要留在浏览器标签页里。如果你需要看完整的 Key 管理文档，可以打开 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Key 的权限说明和额度查看方式。

接下来确认两个关键参数。Base URL 用https://taotoken.net/api，注意这个地址后面不加任何 UTM 参数，直接作为 API 请求前缀。模型 ID 则根据你的场景选择，做文本摘要、分类、问答这类任务，选一个通用对话模型即可；如果你要做代码相关的辅助，可以选 coding 能力更强的模型。模型 ID 的具体名称在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 可以看到，也可以直接在模型对话里试跑一句，确认这个模型 ID 能正常返回。

如果你后续要做长期的编码辅助或者 Agent 类应用，可以了解一下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用的场景。但本篇聚焦的是 Django 服务端的一次性接口调用，用普通 API Key 就够了。

拿到这三样东西——Base URL、API Key、Model ID——就可以进入配置环节了。记住这三个值后面会分别写进 settings 和.env文件，服务层代码里不会出现任何硬编码的凭证。

3. 可复制配置：settings 片段与服务层封装

这一节是整篇的核心，给出可以直接复制进项目的配置和代码。先规划目录结构，在原有 Django 项目基础上新增一个services包，放在项目根目录或者某个 app 下都可以，推荐放在项目级，因为 AI 调用可能被多个 app 复用：

myproject/ ├── config/ │ ├── settings/ │ │ ├── base.py │ │ └── local.py │ └── urls.py ├── services/ │ ├── __init__.py │ └── ai_client.py ├── apps/ │ └── ... ├── .env └── manage.py

第一步，安装依赖。服务层用httpx而不是requests，因为 httpx 原生支持超时配置和连接池，对后端服务更友好：

pip install httpx python-dotenv

第二步，在.env文件里写入凭证。这个文件不要提交到 git，加到.gitignore里：

# .env TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=你的模型ID TAOTOKEN_TIMEOUT=30

第三步，在config/settings/base.py里读取环境变量并暴露成 Django 配置。这里用python-dotenv在 settings 顶部加载.env，然后用os.environ.get读取，给出合理的默认值：

# config/settings/base.py import os from pathlib import Path from dotenv import load_dotenv BASE_DIR = Path(__file__).resolve().parent.parent.parent load_dotenv(BASE_DIR / ".env") # ... 其他原有配置 ... # AI 服务配置 TAOTOKEN_API_KEY = os.environ.get("TAOTOKEN_API_KEY", "") TAOTOKEN_BASE_URL = os.environ.get("TAOTOKEN_BASE_URL", "https://taotoken.net/api") TAOTOKEN_MODEL_ID = os.environ.get("TAOTOKEN_MODEL_ID", "") TAOTOKEN_TIMEOUT = int(os.environ.get("TAOTOKEN_TIMEOUT", "30"))

这样配置的好处是，本地开发用.env，生产环境用系统环境变量注入，settings 代码完全不用改。如果你用django-environ也可以，原理一样，关键是凭证只从环境读取，不写死在代码里。

第四步，写服务层services/ai_client.py。这个模块对外只暴露一个函数chat_completion，内部处理请求构造、超时、错误转换。视图层拿到的是一个干净的字符串或者结构化结果，不需要关心 HTTP 细节：

# services/ai_client.py import logging import httpx from django.conf import settings logger = logging.getLogger(__name__) class AIServiceError(Exception): """AI 调用统一异常，视图层捕获这个即可""" def __init__(self, message, status_code=None): self.message = message self.status_code = status_code super().__init__(message) def chat_completion(prompt, system_prompt=None, temperature=0.7, max_tokens=1024): """ 统一的对话补全调用入口。 返回模型输出的文本内容。 """ api_key = settings.TAOTOKEN_API_KEY if not api_key: raise AIServiceError("TAOTOKEN_API_KEY 未配置", status_code=500) messages = [] if system_prompt: messages.append({"role": "system", "content": system_prompt}) messages.append({"role": "user", "content": prompt}) payload = { "model": settings.TAOTOKEN_MODEL_ID, "messages": messages, "temperature": temperature, "max_tokens": max_tokens, } headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } url = f"{settings.TAOTOKEN_BASE_URL.rstrip('/')}/v1/chat/completions" try: with httpx.Client(timeout=settings.TAOTOKEN_TIMEOUT) as client: resp = client.post(url, json=payload, headers=headers) except httpx.TimeoutException: logger.error("AI 调用超时") raise AIServiceError("AI 服务响应超时", status_code=504) except httpx.RequestError as exc: logger.error("AI 调用网络错误: %s", exc) raise AIServiceError("AI 服务网络异常", status_code=502) if resp.status_code == 401: raise AIServiceError("API Key 无效或已过期", status_code=401) if resp.status_code == 429: raise AIServiceError("请求频率超限", status_code=429) if resp.status_code >= 400: logger.error("AI 调用失败: %s %s", resp.status_code, resp.text[:500]) raise AIServiceError(f"AI 服务返回错误 {resp.status_code}", status_code=502) data = resp.json() try: return data["choices"][0]["message"]["content"] except (KeyError, IndexError) as exc: logger.error("AI 返回结构异常: %s", data) raise AIServiceError("AI 返回结构解析失败", status_code=502)

这段代码有几个工程化细节值得说明。第一，异常统一成AIServiceError，视图层只需要try/except AIServiceError，不用去分辨 httpx 的各种异常类型。第二，超时和网络错误分开处理，返回不同的状态码，方便前端区分是重试还是提示用户。第三，日志里只记录状态码和响应片段，不打印完整 Key。第四，url拼接时对 Base URL 做了rstrip('/')，避免出现双斜杠。

第五步，在 DRF 视图里调用。假设你有一个文章模型，想加一个「AI 生成摘要」的接口：

# apps/articles/views.py from rest_framework.views import APIView from rest_framework.response import Response from rest_framework import status from services.ai_client import chat_completion, AIServiceError class ArticleSummaryView(APIView): def post(self, request): content = request.data.get("content", "").strip() if not content: return Response({"detail": "content 不能为空"}, status=status.HTTP_400_BAD_REQUEST) try: summary = chat_completion( prompt=f"请用不超过 100 字总结以下内容：\n\n{content}", system_prompt="你是一个专业的中文文本摘要助手。", temperature=0.3, ) except AIServiceError as exc: return Response({"detail": exc.message}, status=exc.status_code or 502) return Response({"summary": summary})

到这里，配置和服务层就完成了。整个改动只新增了一个services包、几行 settings、一个视图，原有工作流完全没动。接下来验证它能不能跑通。

4. 验证请求：从 Django shell 到 curl 的端到端联调

配置写完之后不要急着写更多业务，先用最小成本验证一次调用链路。验证分两层：先在 Django shell 里验证服务层本身，再用 curl 验证 HTTP 接口。

第一层，Django shell 验证服务层。进入 shell：

python manage.py shell

然后执行：

from services.ai_client import chat_completion, AIServiceError try: result = chat_completion( prompt="用一句话解释什么是 Django ORM。", system_prompt="你是 Python 后端专家，回答简洁。", temperature=0.2, max_tokens=200, ) print("调用成功：") print(result) except AIServiceError as e: print(f"调用失败：{e.message} (status={e.status_code})")

如果配置正确，你会看到模型返回的一段中文解释。这一步验证的是 settings 读取、Key 有效性、Base URL 拼接、返回结构解析这四件事。如果这里就报错，直接跳到第 5 节排查，不要继续往下走。

第二层，启动开发服务器，用 curl 验证 DRF 接口：

python manage.py runserver 0.0.0.0:8000

另开一个终端，发送请求：

curl -X POST http://127.0.0.1:8000/api/articles/summary/ \ -H "Content-Type: application/json" \ -d '{"content": "Django 是一个基于 Python 的高级 Web 框架，它鼓励快速开发和干净、实用的设计。Django 遵循 MVC 架构模式，在 Python 中通常称为 MTV（模型-模板-视图）。它自带 ORM、认证系统、管理后台等组件，适合构建中大型 Web 应用。"}'

预期返回类似：

{ "summary": "Django 是基于 Python 的高级 Web 框架，采用 MTV 架构，自带 ORM、认证和管理后台，适合快速开发中大型 Web 应用。" }

如果返回的是{"detail": "..."}，说明服务层抛出了AIServiceError，detail里的信息就是排查线索。如果返回 404，检查config/urls.py里有没有把这个视图的路由挂上去：

# config/urls.py from django.urls import path from apps.articles.views import ArticleSummaryView urlpatterns = [ path("api/articles/summary/", ArticleSummaryView.as_view()), ]

验证通过之后，建议再做一次「异常路径」验证，确认错误处理真的生效。比如临时把.env里的 Key 改错一位，重启服务，再发一次 curl，应该返回 401 和「API Key 无效或已过期」。这一步很多人会跳过，但它是保证线上出问题时你能快速定位的关键。验证完记得把 Key 改回来。

到这里，一次完整的端到端调用就验证完了：settings 读取配置 → 服务层构造请求 → TaoToken 返回结果 → 视图层包装成 JSON。整个过程没有改动任何原有的 models 和 serializers，AI 能力是作为一个独立服务层挂上去的。

5. 常见报错排查：401、超时、choices 解析失败逐个击破

这一节把接入过程中最容易遇到的几类报错列出来，对照你的实际错误信息定位。这些错误我在不同项目里基本都遇到过，按出现频率排序。

报错一：401 Unauthorized，返回{"detail": "API Key 无效或已过期"}

这是最高频的问题。排查顺序如下。先确认.env里的TAOTOKEN_API_KEY是不是完整的sk-开头字符串，有没有多余空格或换行。然后确认 settings 里load_dotenv的路径对不对，如果.env放在项目根目录而BASE_DIR指向了别处，就会读不到。可以在 shell 里打印确认：

from django.conf import settings print(repr(settings.TAOTOKEN_API_KEY[:10])) print(settings.TAOTOKEN_BASE_URL)

如果 Key 打印出来是空字符串，说明环境变量没加载成功。如果 Key 正常但依然 401，去控制台 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认这个 Key 是否被禁用或额度耗尽。还有一种情况是 Key 复制时漏了字符，重新生成一个最省事。

报错二：local proxy failed或连接被拒绝

这个报错通常出现在请求根本没发出去的时候。检查TAOTOKEN_BASE_URL是不是写成了https://taotoken.net/api/带了尾部斜杠，虽然代码里做了rstrip('/')，但如果你在别处手动拼接了 URL 就可能出问题。另外确认你的服务器或本地网络能正常访问外网 HTTPS，公司内网如果有出口限制，需要让运维放行taotoken.net域名。注意这里说的是正常的网络出口配置，不是任何绕过网络管理的手段。

报错三：AI 返回结构解析失败，日志里能看到choices相关

这个错误来自服务层里data["choices"][0]["message"]["content"]这一段。可能的原因有三个。一是模型返回了非预期结构，比如某些模型在特定参数下返回的是流式分片，而你没有开启流式解析。二是max_tokens设置过小，模型还没输出内容就被截断，choices为空数组。三是请求体里的model字段填错了，服务端返回了一个错误对象而不是正常的补全结果。排查方法是在服务层临时打印完整响应：

import json print(json.dumps(data, ensure_ascii=False)[:800])

看清楚返回的 JSON 长什么样，再决定是改参数还是改解析逻辑。如果是模型 ID 问题，去模型对话页面确认正确的 ID 名称。

报错四：AI 服务响应超时，status 504

超时通常是两个原因：网络慢或者max_tokens太大导致模型生成时间长。先把TAOTOKEN_TIMEOUT从 30 调到 60 试试。如果还是超时，把max_tokens降到 512 以内，看是否能返回。对于摘要这类任务，输出本来就不需要很长，max_tokens设太大反而浪费。另外注意，Django 开发服务器是单线程的，如果你在视图里同步调用 AI 且并发请求多，会互相阻塞，生产环境建议用 gunicorn 多 worker 或者把 AI 调用放到异步任务队列里。

报错五：DRF 返回 500 但日志里没有明显错误

检查视图里有没有捕获AIServiceError。如果服务层抛出的异常没有被视图捕获，Django 会返回 500 并且堆栈里是AIServiceError。确认你的except写的是AIServiceError而不是Exception，并且exc.status_code有值。如果status_code是None，Response会报错，所以服务层里每个raise都带了状态码。

把这几类错误对照排查一遍，基本能覆盖 90% 的接入问题。剩下的边缘情况，看日志里的resp.text[:500]输出，通常能直接看出服务端返回的错误描述。

6. 把 AI 调用沉淀成 Django 项目的基础设施

走到这里，你已经有了一个能跑通的 AI 调用链路。但真正让这套方案有价值的，是把它当成项目的基础设施来维护，而不是一次性代码。几个可以继续做的方向。

第一，给服务层加缓存。摘要、分类这类任务，同样的输入没必要重复调用。用 Django 的 cache 框架包一层：

from django.core.cache import cache import hashlib def cached_chat_completion(prompt, **kwargs): key = "ai:" + hashlib.md5(prompt.encode()).hexdigest() result = cache.get(key) if result is None: result = chat_completion(prompt, **kwargs) cache.set(key, result, timeout=3600) return result

第二，把模型 ID 做成可配置的多模型路由。比如摘要用便宜快的模型，代码生成用能力强的模型，在 settings 里定义多个模型 ID，服务层根据任务类型选择。这样后续换模型不用改业务代码。

第三，加调用统计。在服务层里记录每次调用的耗时和 token 消耗，写到日志或者数据库，方便做成本监控。TaoToken 控制台也能看用量，但项目内部的统计更细粒度。

第四，如果你后续要做更复杂的 Agent 或者长期编码辅助，可以了解 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对高频调用场景做了优化。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有更完整的参数说明。

最后提醒一点：服务层的chat_completion函数签名保持稳定，内部实现可以随时替换。今天用 TaoToken 的兼容接口，明天如果要换别的后端，只改这一个文件就行，视图层完全无感。这就是把 AI 调用收敛到服务层的最大价值——业务代码不感知底层模型的变化。