AI 大模型推理 > API 文档 > 聊天补全接口参数说明

聊天补全接口参数说明

最近更新时间: 2025-12-18 12:26:35

聊天补全接口参数说明

概述

本文档描述了聊天补全接口的请求参数，该接口用于生成对话模型的响应。支持多种模型配置和生成控制参数。

请求参数

基本信息参数

参数名	类型	必填	默认值	说明
`model`	string	是	-	指定使用的模型名称。例如：“gemini-2.5-flash” 等
`messages`	array	是	-	对话消息数组，包含对话历史记录
`stream`	boolean	否	`false`	是否启用流式响应

消息格式

messages 数组中的每个元素应包含：

role: 消息角色，可选值："system", "user", "assistant", "tool"
content: 消息内容，可以是字符串或复杂内容对象
name (可选): 参与者名称
tool_calls (可选): 工具调用信息
tool_call_id (可选): 工具调用ID（仅当role为"tool"时）

生成控制参数

参数名	类型	必填	默认值	范围/示例	说明
`max_tokens`	integer	否	模型默认值	≥1	生成的最大令牌数
`temperature`	float32	否	1.0	[0.0, 2.0]	采样温度。值越高输出越随机，值越低输出越确定
`top_p`	float32	否	1.0	[0.0, 1.0]	核采样参数。仅考虑累计概率达到此值的令牌
`top_k`	integer	否	-	≥1	仅从概率最高的k个令牌中采样
`presence_penalty`	float32	否	0.0	[-2.0, 2.0]	存在惩罚。正值惩罚已出现的令牌，鼓励新内容
`frequency_penalty`	float32	否	0.0	[-2.0, 2.0]	频率惩罚。正值惩罚频繁出现的令牌。个别模型不支持或范围不同
`repetition_penalty`	float32	否	1.0	[0.0, 2.0]	重复惩罚。>1.0时减少重复内容。个别模型不支持或范围不同

思维链参数（Anthropic/OpenAI标准）

参数名	类型	必填	说明
`thinking`	ThinkType	否	思维链配置，控制模型的推理过程显示，“thinking”: {“type”:“enabled”, “budget_tokens”:160}不同gemini版本会有差异
`reasoning_effort`	string	否	推理强度控制，如：“low”, “medium”, “high”，在大部分模型上，这两个思考参数都可以使用

工具调用参数

参数名	类型	必填	说明
`tools`	FunctionTools	否	可供模型调用的工具定义列表
`tool_choice`	interface{}	否	工具调用策略。可选值： - `"none"`: 不调用工具 - `"auto"`: 由模型决定 - `"required"`: 必须调用工具 - 对象: 指定具体工具

多模态支持

参数名	类型	必填	说明
`image_config`	ImageConfig	否	图像输入配置，用于多模态模型处理图像
`response_format`	ResponseFormat	否	响应格式控制，如：`{"type": "json_object"}` 或 `{"type": "text"}`

使用示例

基础对话

{
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "你好，今天天气怎么样？"}
  ],
  "temperature": 0.7,
  "max_tokens": 500
}

工具调用

{
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "查询北京的天气"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

流式响应

{
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "写一首关于春天的诗"}
  ],
  "stream": true,
  "temperature": 0.8
}

带图像的对话

{
  "model": "gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
      ]
    }
  ],
  "max_tokens": 300
}

参数最佳实践

温度设置：
- 创造性任务：0.7-0.9
- 事实性回答：0.1-0.3
- 代码生成：0.1-0.3
惩罚参数：
- 减少重复：设置 repetition_penalty 为 1.1-1.2
- 鼓励多样性：设置 presence_penalty 为 0.1-0.5
长度控制：
- 对话场景：max_tokens 设置为 500-1000
- 摘要场景：根据原文长度适当调整
工具调用：
- 明确指定工具功能描述
- 使用 tool_choice: "auto" 让模型自主决定
- 需要强制工具调用时使用 tool_choice: "required"

注意事项

所有浮点数参数应在指定范围内，超出范围可能导致错误
流式响应时，客户端需要处理分块数据
工具调用需要配合后续的工具响应消息
图像输入需要模型支持多模态能力
不同模型可能对参数有不同支持程度，请参考具体模型文档

错误处理

常见错误码：

400: 参数验证失败
401: 认证失败
429: 速率限制
500: 服务器内部错误

建议实现重试逻辑和适当的错误处理机制。

以上内容是否对您有帮助？