对话式AI助手接入配置实战：从鉴权到验证

一、开始之前

本文讲的是通用接入方法。文中的域名、路径、字段名都是占位示例，实际使用时请以你所用平台的官方文档为准。本文不覆盖图像、视频生成和多智能体编排，这些能力适合单独成文。

阅读本文需要具备以下基础：

• 能够调用 HTTP 接口，理解请求方法、请求头和 JSON 请求体；
• 理解密钥、令牌这类鉴权概念；
• 能够查看日志并定位简单错误。

完成本文后，你应当能够：

• 用最小请求确认凭证和网络都正常；
• 配置系统指令、流式输出、联网检索、记忆和多语言能力；
• 用可重复的用例验证配置，并定位常见故障；
• 按安全和稳定性要求完成上线前检查。

二、环境与鉴权

2.1 创建应用与凭证

在平台控制台创建应用，并为开发、测试、生产环境分别创建凭证。这样测试流量不会消耗生产配额，凭证泄露时也能只吊销对应环境的密钥。

凭证只授予当前用途需要的权限。如果平台支持，为服务账号设置最小权限，不要直接使用管理员账号。

验收标准：控制台能看到新建应用，凭证状态显示为有效，且有效期和权限范围已记录在团队文档中。

2.2 注入凭证

密钥不能写进源码，也不能提交到代码仓库。推荐通过环境变量或配置中心注入：

export AI_ASSISTANT_ENDPOINT="https://api.example.com/v1"
export AI_ASSISTANT_API_KEY="<你的密钥>"

应用启动时读取这两个变量。如果缺少任一变量，程序应当直接报错退出，而不是带着空值继续运行。

2.3 发送最小请求

最小请求只包含一条用户消息。它能帮你判断问题出在网络、凭证还是请求格式上。

请求说明：

项目	取值（占位示例）
请求方法	POST
请求路径	/chat/completions
请求头	Authorization: Bearer 密钥；Content-Type: application/json
必填字段	model（模型标识）、messages（消息数组）
建议超时	连接 5 秒，读取 60 秒

示例请求：

curl -sS -X POST "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer <你的密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型标识>",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你的能力"}
    ]
  }'

示例响应（结构示意，字段名以文档为准）：

{
  "id": "req_xxxxxx",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 20, "completion_tokens": 40}
}

验收标准：HTTP 状态码为 200，choices[0].message.content 非空，finish_reason 为 stop。响应中的请求 ID 要记入日志，方便后续排错。

常见返回码的含义如下：

• 401：凭证错误、过期或未正确注入；
• 403：凭证有效，但没有调用该模型或接口的权限；
• 429：请求过于频繁或配额用尽；
• 5xx：服务端异常，可稍后重试。

三、能力配置

3.1 对话、系统指令与流式输出

系统指令用于约束助手的角色、语气和回答边界。把它放在 messages 数组的第一位，并且只在服务端设置，不让终端用户直接修改。

{
  "model": "<模型标识>",
  "messages": [
    {"role": "system", "content": "你是业务助手。回答简洁，给出依据。无法确定时请明确说明。"},
    {"role": "user", "content": "请说明本产品的退款流程"}
  ],
  "temperature": 0.3,
  "stream": true
}

几个参数的设置建议：

• temperature：业务问答建议取较低值，例如 0.2 到 0.5，以保证回答稳定。这是经验值，需要用你的测试集验证。
• stream：长回答场景建议开启。多数平台以 SSE 格式返回，每行以 data: 开头，结束时发送结束标记。具体格式请对照文档。客户端需要逐块读取并拼接，不能等整个响应结束再解析。
• 推理过程展示：只有平台文档明确给出对应参数时才开启，并确认它会增加输出长度和费用。如果文档没有说明，就不要在产品中承诺这项功能。

验收标准：同一问题重复提问 3 次，回答的结构和语气一致；开启流式后，首个数据块在你设定的阈值内到达，例如 2 秒；拼接全部数据块后，内容完整且以结束标记收尾。

3.2 联网检索与来源引用

联网检索让助手获取最新信息，并在回答中附带来源。它的风险在于来源质量参差不齐，因此配置时要设置域名白名单，并在前端校验引用。

建议配置以下内容：

• 检索开关：字段名以平台文档为准，示例中用 search.enabled 表示；
• 数据源白名单：只允许检索指定域名，示例中用 allowed_domains 表示；
• 结果数量上限：例如 max_results 设为 5，减少无关内容；
• 引用返回字段：确认响应中是否包含 citations 或同类字段。

请求示例（字段名为占位）：

{
  "model": "<模型标识>",
  "messages": [
    {"role": "system", "content": "回答涉及最新信息时必须给出来源。无可靠来源时说明不确定。"},
    {"role": "user", "content": "本产品最新版本的发布日期是什么？"}
  ],
  "search": {
    "enabled": true,
    "allowed_domains": ["docs.example.com"],
    "max_results": 5
  }
}

前端展示引用前，建议做以下检查：

1. 引用链接必须是 https 地址；
2. 链接域名必须在白名单内；
3. 没有引用时，界面明确提示“未找到可靠来源”，不要直接展示模型的推断。

验收标准：提问一个需要最新信息的问题，响应中包含引用字段；随机抽取 5 条链接，均能打开，且域名属于白名单。

3.3 跨对话记忆

记忆功能让助手在多轮会话中保留上下文。配置前，团队要先回答三个问题：记忆存在哪里，保存多久，用户如何删除。

建议的做法如下：

• 存储位置：按公司数据合规要求选择平台托管或自建存储，并写入设计文档；
• 保留时长：建议设置明确期限，例如 30 天，到期自动清理；
• 删除接口：为用户提供删除入口，示例路径为 DELETE /memories/{user_id}，请以平台文档为准；
• 数据最小化：只保存业务必要的信息，身份证号、手机号、银行卡号等敏感字段写入前必须脱敏或直接丢弃。

验收标准：第一轮提供某个信息，第二轮提问时助手能正确引用；调用删除接口后，同一用户的新会话不再引用旧信息；检查存储内容，确认没有明文敏感字段。

3.4 多语言回复

多语言配置分两步：确认目标语言在平台支持列表中，再决定回复语言的来源。

回复语言有两种常见方式：

• 固定语言：在系统指令中写明“始终使用简体中文回复”；
• 跟随用户：在系统指令中写明“使用用户提问所用的语言回复”。

建议准备一份测试集，至少包含中文、英文、日文和一种小语种各 5 条问题。

验收标准：测试集中所有回复的语言与配置一致，专有名词和数字格式没有明显错误。

3.5 自定义指令

如果允许用户调整回复风格，就必须限制输入。自定义指令可能携带恶意