Chat Completions API

最常用的对话 API，完全兼容 OpenAI Chat Completions 接口。

POST/v1/chat/completions创建聊天对话

POST https://hub.lurus.cn/v1/chat/completions

流式响应

SSE 逐 Token 返回

Function Calling

让模型调用你的函数

多模态 Vision

混合传入文字与图片

最佳实践

温度 / System Prompt / 多轮

---

请求参数

必填

参数	类型	说明
model	string	模型名称，如 deepseek-chat、gpt-4o
messages	array	对话消息数组，见下方格式

常用可选参数

参数	类型	默认值	说明
temperature	number	1.0	随机性（0–2）。代码/数学用 0.1，创意写作用 0.9
max_tokens	integer	—	最大生成 Token 数。不设置则由模型决定
stream	boolean	false	流式输出Streaming流式响应，AI 模型逐 Token 返回结果（而非等全部生成完），降低首字延迟。Server-Sent Events streaming（SSE），见流式响应
top_p	number	1.0	核采样，与 temperature 通常二选一调整
stop	string/array	—	遇到此字符串时停止生成
n	integer	1	同时生成几个候选回复
user	string	—	用户标识符，用于审计日志

Messages 格式

[
  {"role": "system",    "content": "你是一位专业的技术顾问。"},
  {"role": "user",      "content": "什么是 RESTful API？"},
  {"role": "assistant", "content": "RESTful API 是…"},
  {"role": "user",      "content": "能举个例子吗？"}
]

角色	用途
system	设定 AI 的行为、语气和限制。放在数组第一个
user	用户的输入
assistant	AI 的回复。多轮对话时需要把历史回复包含在内

完整请求体（ChatCompletionRequest）与消息（Message）的全部字段定义见 数据结构参考。

---

基础示例

---

流式响应

设置 stream: true，响应通过 Server-Sent Events 逐 Token 返回，适合聊天类应用。

流式数据格式

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"落"},"index":0}]}
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"叶"},"index":0}]}
...
data: [DONE]

TIP

最后一个 data: [DONE] 表示流结束，此时 delta.content 为空。

---

Function Calling

让 AI 决定何时调用你提供的函数，并返回结构化参数（Tool CallTool CallAI 模型在推理过程中决定调用外部工具（如搜索、数据库查询），并返回结构化的调用参数。）。适用于搜索、查询数据库、调用外部 API 等场景。

工作流程

Function Calling 调用流程

graph LR; A[你的请求<br/>含 tools 定义] --> B[模型返回<br/>finish_reason: tool_calls]; B --> C[你执行函数<br/>结果以 role: tool 传回]; C --> D[模型结合结果<br/>生成最终回答]

完整示例：查询天气

模型支持

Function Calling 需要模型支持。推荐使用 gpt-4o、gpt-4o-mini、claude-3-5-sonnet。 DeepSeek 系列也支持，但参数格式有细微差异，测试时注意验证。

---

多模态输入（Vision）

部分模型可以理解图片内容，在 content 中混合传入文字和图片。

支持 Vision 的模型

gpt-4o、gpt-4o-mini、gemini-3-pro-preview、gemini-3-pro-image-preview

图片大小限制：URL 图片需公网可访问；Base64 建议单张不超过 5 MB。

---

最佳实践

System Prompt 写法

{
  "role": "system",
  "content": "你是一位专业客服。请用友好简洁的语气回答，每条回复不超过 150 字。如遇无法回答的问题，引导用户联系 support@lurus.cn。"
}

好的 System Prompt 包含：角色定义 + 语气要求 + 长度限制 + 边界处理。

温度设置参考

场景	temperature	说明
代码生成、数学计算	0.0–0.2	确定性高，减少随机
问答、摘要、分类	0.3–0.6	准确但有一定灵活性
创意写作、头脑风暴	0.7–1.0	多样性强
随机故事、角色扮演	1.0–1.5	高创意，可能不稳定

多轮对话管理

conversation = [
    {"role": "system", "content": "你是一位历史老师。"}
]

def chat(user_input: str) -> str:
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=conversation,
        max_tokens=500
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

print(chat("秦始皇是谁？"))
print(chat("他有哪些重要成就？"))  # 模型能记住上文的"秦始皇"

上下文窗口管理

每个模型的上下文长度有限（如 deepseek-chat 是 64K tokens）。对话过长时，可以：

1. 截断最旧的消息（保留 system + 最近 N 轮）
2. 定期总结历史对话，压缩 Token 用量

---

错误处理

常见状态码：400 请求格式错误 → 检查 JSON 结构和必填参数；401 Key 无效/过期；403 无权访问此模型 → 联系管理员；429 超出速率限制 → 指数退避重试；500/502 上游模型异常 → 重试或切换备用模型。完整错误码和重试策略见 错误处理。

---

下一步

错误处理数据结构 / Schema认证API 概述支持的模型