通用 API 使用规范 · Dylan AI Agent Nexus

定位与适用对象

本页总结如何正确调用第三方/公有云/模型推理类 API 的通用规范，适用于 ChatGPT/DeepSeek/Qwen/Llama 等大语言模型接口、向量检索、自动化平台（n8n）以及企业内部系统集成场景。

认证与权限

• API Key：常见于模型调用。使用 HTTP Header（如 Authorization: Bearer <key>）。密钥放入安全配置中心，避免写死代码。
• Basic：Authorization: Basic base64(user:pass)，仅在 HTTPS 下使用。
• OAuth 2.0：对接企业系统优先（Client Credentials / Authorization Code），统一密钥轮换与最小权限。

请求/响应与错误规范

• 内容格式：统一 Content-Type: application/json；时间用 ISO8601（UTC）。
• 错误返回：HTTP Code + 错误体（{ code, message, details }）。客户端根据 4xx/5xx 做重试与提示。
• 分页：推荐 cursor/next_token 风格；避免 page/size 在大数据量下的偏移成本。
• 速率限制：读取 RateLimit-* 与 Retry-After 头；退避重试（指数 + 抖动）。
• 幂等性：对转账/写入类接口使用 Idempotency-Key 请求头，服务端以 Key 去重。

LLM 通用调用模式（Chat 系列）

聊天接口通常遵循 messages[] 约定（system/user/assistant 角色），支持 temperature、top_p、max_tokens 等参数，并可选择流式输出（SSE/Chunk）。

curl -X POST https://api.example.com/v1/chat/completions 
  -H "Authorization: Bearer $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model":"gpt-4o-mini",
    "messages":[
      {"role":"system","content":"You are a helpful assistant."},
      {"role":"user","content":"帮我写一份技术周报提纲"}
    ],
    "temperature":0.7,
    "stream":true
  }'

• 上下文预算：关注模型上下文窗口限制；长文建议摘要/RAG 切片与检索。
• 函数/工具调用：部分模型支持 function/tool calling；先返回 schema，再据此调用外部工具并把结果回注对话。
• 流式输出：通过 SSE/Chunk 提升首 token 速度；客户端需拼接 delta 内容并处理 [DONE] 结束标记。

文件上传与向量检索

• 上传：使用 multipart/form-data 或预签名 URL；大文件分片与断点续传。
• 向量化：调用 Embedding API 生成向量，写入向量库（维度/度量/索引类型需匹配）。
• RAG：检索相关片段后，拼入聊天 messages 作为 context，并标注引用来源。

Webhook 与异步任务

• 签名校验：使用 HMAC（sha256）在 X-Signature 头传递签名；服务端按时间戳窗口校验重放。
• 可重试：采用指数退避；幂等性由事件 ID 保证。回调 2xx 视为成功。
• 事件契约：定义 event 与 data 字段；新增事件先灰度发布。

安全与合规

• 最小权限：按环境与用途分配最小权限密钥；对外接口只暴露必要字段。
• 敏感信息：日志脱敏；PII/机密文本加密存储；传输使用 TLS1.2+。
• 可观察性：记录请求 ID、延迟、错误码、消耗 Token；建立配额与告警。

版本管理与多环境

• 版本化：路径版本（/v1）或 Accept: application/vnd.company.v1+json；变更遵循兼容策略。
• 多环境：Dev/Staging/Prod 分离；密钥与回调地址分环境管理，禁止交叉使用。

系统集成示例（思路）

1. 消息编排：n8n 定时/表单触发 → 调用 LLM 生成文案 → 写入 CMS → 通知审核群。
2. 知识问答：文档上传 → 向量化入库 → Chat 接口检索增强 → 返回带引用答案。
3. 工单自动化：Webhook 收到事件 → 分类与摘要 → 生成回复草稿 → 人工确认后发送。

参考实现（简化）

import requests

headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
payload = {
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "给出3条标题建议"}
  ],
  "temperature": 0.6
}
res = requests.post("https://api.example.com/v1/chat/completions", json=payload, headers=headers, timeout=60)
res.raise_for_status()
print(res.json())

把以上规范落地到任何模型/自动化/企业系统 API，都能获得更稳定、可维护与可审计的集成效果。