MastraMastra
  • 文档
  • 大模型
⌘ K
文本生成模型
大语言模型
OpenAI API
流式传输
最后更新时间：
帮助改进此文档
Made with ❤️ by 紫升
本页访问量 | 本站总访问量 | 本站总访人数

TABLE OF CONTENTS

client.chat.completions.crate

入参

参数类型必填默认值说明
modelstring✅ 是—模型 ID，如 "gpt-4o", "qwen-plus", "deepseek-chat"
messagesArray<Message>✅ 是—对话历史列表，按时间顺序排列
frequency_penaltynumber❌ 否0[-2, 2]，值越高越抑制重复词
logit_biasobject❌ 否null调整特定 token 的生成概率（token ID → bias 值）
logprobsboolean❌ 否false是否返回输出 token 的 log 概率
top_logprobsinteger❌ 否—若 logprobs=true，返回每个位置 top N token 概率（1~20）
max_tokensinteger❌ 否模型最大上下文限制生成的最大 token 数（不含输入）
ninteger❌ 否1返回多少个独立 completion 结果（1~128）
presence_penaltynumber❌ 否0[-2, 2]，值越高越鼓励新话题
response_formatobject❌ 否—强制输出格式
seedinteger❌ 否null随机种子，用于确定性输出（部分模型支持）
stopstring | Array❌ 否null遇到这些字符串立即停止生成
streamboolean❌ 否false是否启用流式响应（逐 token 返回）
stream_optionsobject❌ 否—流式选项（见下表）
temperaturenumber❌ 否1[0, 2]，控制随机性（0=确定，1=默认，2=高创意）
top_pnumber❌ 否1[0,1]，核采样概率阈值（与 temperature 二选一）
toolsArray<Tool>❌ 否—定义可调用的函数工具（见下表递归）
tool_choicestring | object❌ 否"auto"控制是否/如何调用工具
userstring❌ 否—用户唯一标识（用于滥用监控，非必需）

Message 对象

字段类型必填说明
rolestring✅角色："system" / "user" / "assistant" / "tool"
contentstring | null | Array<ContentPart>✅文本内容，或多媒体内容列表（多模态模型）
namestring❌（仅 role="tool"）工具名称
tool_call_idstring❌（仅 role="tool"）对应 tool call ID
tool_callsArray<ToolCall>❌（仅 role="assistant"）模型请求的工具调用

ContentPart（多模态输入，如 GPT-4o/Qwen-VL）

字段类型说明
typestring"text" 或 "image_url"
textstring（当 type="text"）文本内容
image_urlobject（当 type="image_url"）图片信息

image_url

字段类型说明
urlstring图片 URL（支持 base64）
detailstring"low" / "high" / "auto"（GPT-4o 特有）

ToolCall

字段类型说明
idstring工具调用唯一 ID
type"function"固定值
functionobject函数信息（见下）
function（在 tool_calls 中）
字段类型说明
namestring函数名
argumentsstringJSON 字符串，表示参数

tools 中的 Tool

字段类型说明
typestring固定为 "function"
functionobject函数定义

tools 中的function

字段类型必填说明
namestring✅函数名（字母/下划线，无空格）
descriptionstring❌函数描述（帮助模型理解用途）
parametersobject✅JSON Schema 格式的参数定义

INFO

💡 parameters 遵循 JSON Schema 规范，例如：

json
{
  "type": "object",
  "properties": {
    "location": { "type": "string", "description": "城市名" }
  },
  "required": ["location"]
}

tool_choice

类型示例说明
string"none" / "auto" / "required"控制是否调用工具
object{ "type": "function", "function": { "name": "get_weather" } }强制调用指定函数

response_format

字段类型必填说明
type"text""json_object"✅
json_schemaobject❌（部分平台支持）JSON Schema 定义

stream_options

字段类型说明
include_usageboolean是否在流结束时返回 usage

非流式响应

调用成功后返回的对象结构（以非流式 stream=false 为例）。

字段类型说明
idstring请求唯一 ID（如 chatcmpl-abc123）
objectstring固定为 "chat.completion"
createdintegerUnix 时间戳（秒）
modelstring实际使用的模型 ID
choicesArray<Choice>生成结果列表（长度 = n）
usageUsagetoken 消耗统计
system_fingerprintstring模型配置指纹（OpenAI 特有）

choices → Choice

字段类型说明
indexinteger结果序号（0 ~ n-1）
messageMessage生成的消息（结构同入参 messages 元素）
logprobsobject | nulltoken 概率信息（若请求中 logprobs=true）
finish_reasonstring结束原因： "stop"（正常结束）、 "length"（达到 max_tokens）、 "tool_calls"（需调用工具）、 "content_filter"（内容被过滤）

💡 message 结构与入参中的 Message 完全一致，可能包含 tool_calls。

usage

字段类型说明
prompt_tokensinteger输入（prompt）消耗的 token 数
completion_tokensinteger输出（completion）消耗的 token 数
total_tokensintegerprompt_tokens + completion_tokens

流式响应

每个 chunk 是一个 ChatCompletionChunk 对象，结构如下：

字段类型说明
idstring同 id
objectstring"chat.completion.chunk"
createdinteger
modelstring
choicesArray<ChunkChoice>流式片段（通常 n=1，所以长度=1）

ChunkChoice

字段类型说明
indexinteger序号
deltaDelta增量内容（见下）
finish_reasonstring | null仅在最后 chunk 非 null

Delta

字段类型说明
rolestring仅在第一个 chunk 出现（如 "assistant"）
contentstring | null新增的文本片段（可能为 null）
tool_callsArray<ToolCallDelta> | null工具调用增量（结构类似 ToolCall）

最终完整消息需拼接所有 delta.content。

总结

  • 入参：你告诉模型“做什么”（对话历史、约束、工具等）
  • 出参：模型告诉你“结果是什么”（回答、token 消耗、是否需调用工具等）