# 模型服务API接入接口规范 当前模型网关支持文本对话（Chat）、文本向量化（Embeddings）、文本排序（Rerank）、图像理解类型的API接入。模型API接入之前，请确保符合相对应的接口规范，其中Chat接口、Embeddings、图像理解接口需要符合OpenAI接口规范，Rerank接口需要符合AI引擎标准协议。 #### 文本对话（Chat）API规范 **接口格式** 类型：POST 协议：HTTP/HTTPS **请求体参数** 表1请求体参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | messages | 是 | Array of [ChatCompletionRequestMessage] objects | 文本对话消息体类。 | | model | 是 | String | 文本对话使用的模型名称。 | | frequency_penalty | 否 | Number | 介于-2.0和2.0之间的数字。 正值会根据文本中新Token的现有频率对其进行惩罚，从而降低模型重复相同行的可能性。 **最小值：-2** **最大值：2** **缺省值：0** | | logit_bias | 否 | Map\ | 该参数接受一个JSON对象，将标记映射到从-100（禁止）到100（独占选择标记）的关联偏差值。 像-1和1这样的适度值将以较小的程度改变选择标记的概率。 使用logit_bias参数时，偏差被添加到模型生成的logits之前进行抽样。 | | max_tokens | 否 | Integer | 返回体允许的最大token数。 | | n | 否 | Integer | 返回体中包含的choices数量，建议默认设置为1，最大限度地降低成本。 **最小值：1** **最大值：128** **缺省值：1** | | presence_penalty | 否 | Number | 介于-2.0和2.0之间的数字。 正值会根据它们是否出现在文本中来惩罚得到新的Token，从而增加模型谈论新主题的可能性。 **最小值：-2** **最大值：2** **缺省值：0** | | stream | 否 | Boolean | 布尔类型。 设为true时，返回结果为流式。 设为false时，返回结果为JSON格式结构化数据。 **缺省值：false** | | temperature | 否 | Number | 较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定。 **最小值：0** **最大值：2** **缺省值：1** | | top_p | 否 | Number | 影响输出文本的多样性，取值越大，生成文本的多样性越强。 **最小值：0.0** **最大值：1.0** **缺省值：1** | | tools | 否 | Array of [FunctionCallTool] objects | 可供模型调用的工具。 | | tool_choice | 否 | String | 用于控制模型是如何选择要调用的函数，仅当工具类型为function时补充。 默认为auto，且当前仅支持auto。 | 表2ChatCompletionRequestMessage | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 是 | String | 消息体对应的角色。 如果是系统则为system。 如果是用户则为user。 枚举值： - **system** - **user** | | content | 是 | String | 消息具体内容。 | | name | 否 | String | 对话参与者的可选名称，提供给模型信息以区分相同角色的不同对话参与者。 | 表3FunctionCallTool | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | 调用工具类型，目前仅支持function。 | | function | 否 | [function] object | 仅当工具类型为function时补充。 | 表4function | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 否 | String | 函数名称，只能包含a-z、A-Z、0-9、下划线和中横线。最大长度限制为64个字符。 | | description | 否 | String | 用于描述函数功能。 模型会根据这段描述决定函数调用方式。 | | parameters | 否 | Object | Json Schema对象，用于定义函数所接受的参数。 | - **非工具调用请求示例** ``` { "model": "my-chat-model", "messages": [ { "role": "system", "content": " You are a helpful assistant. " }, { "role": "user", "content": "你好！" } ], "max_tokens": 20, "presence_penalty": 1.2, "frequency_penalty": 1.0, "temperature": 0.5, "top_p": 0.95, "stream": false } ``` - **工具调用请求示例** ``` { "model": "my-chat-model", "messages": [ { "role": "user", "content": "请帮我查询南京的天气" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "获取给定地点的天气", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "地点，例如北京、上海。" } }, "required": ["location"] } } } ], "max_tokens": 200, "presence_penalty": 1.2, "frequency_penalty": 1.0, "temperature": 0.5, "top_p": 0.95, "stream": false } ``` **响应体参数** 表5响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 文本对话唯一标识符。 | | choices | Array of [choices] objects | 返回体列表。 如果'n'大于1，则结果为多个。 | | created | Integer | 问答发生的时间（格式为时间戳）。 | | model | String | 文本对话使用的模型名称。 | | object | String | 固定值'chat.completion'。 | | usage | [CompletionUsage] object | 文本对话用量统计。 | 表6choices | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | 返回多个choices时，每个choice对应的顺序。 | | message | [ChatCompletionResponseMessage] object | 模型服务返回的具体消息体内容。 | | finish_reason | String | 返回结束的原因。 - **stop：**模型达到自然停止点或提供的停止序列。 - **length：**达到请求中指定的最大令牌数。 - **content_filter：**由于内容过滤器的标志而省略了内容。 - **tool_calls：**模型选择了某个工具。 枚举值： - **stop** - **length** - **content_filter** - **tool_calls** | 表7ChatCompletionResponseMessage | 参数 | 参数类型 | 描述 | |:---|:---|:---| | content | String | 返回消息体的内容，与tool_calls二选一。 | | role | String | 返回消息体的角色。 枚举值： - **assistant** | | tool_calls | Array of [ToolCall] objects | 工具调用消息，与content二选一。 | 表8ToolCall | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 工具调用唯一标识符。 | | type | String | 工具类型，当前仅支持function。 | | function | [CallFunction] Object | 调用函数的详细信息。 | 表9CallFunction | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | 函数名。 | | arguments | String | 调用函数的参数，Json格式。 | 表10CompletionUsage | 参数 | 参数类型 | 描述 | |:---|:---|:---| | completion_tokens | Integer | 回答包含的token数。 | | prompt_tokens | Integer | 提问包含的token数。 | | total_tokens | Integer | 提问+回答token总数。 | - **非流式响应示例** - 非工具调用 ``` { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1718772336, "model": "my-chat-model", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好，有什么我可以帮助你的吗？" }, "finish_reason": "stop", "logprobs": null } ], "usage": { "prompt_tokens": 5, "completion_tokens": 10, "total_tokens": 15 } } ``` - 工具调用 ``` { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1718772336, "model": "my-chat-model", "choices": [ { "index": 0, "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"location\": \"南京\"}" } } ] }, "finish_reason": "tool_calls", "logprobs": null } ], "usage": { "prompt_tokens": 5, "completion_tokens": 10, "total_tokens": 15 } } ``` - **流式响应示例** - 非工具调用 ``` {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"你好"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"，"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"有"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"什么"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"我"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"可以"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"帮助"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"你"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"的"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"吗"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"content":"？"},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} ``` - 工具调用 流式返回的工具调用信息必须在一条消息内，不能分拆返回。 ``` {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{"role":"assistant","content":null,"tool_calls":[{"id":"call_123","type":"function","function":{"name":"get_weather","arguments":"{\"location\":\"南京\"}"}}]}"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1718772336,"model":"my-chat-model","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"tool_calls"}]} ``` #### 文本向量化（Embeddings）API规范 **接口格式** 类型：POST 协议：HTTP/HTTPS **请求体参数** 表11请求体参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | input | 是 | Array of strings | 输入支持2种格式： - **纯文本（string）**，例如，"你好" 。 - **文本列表（array）**，例如，\["你","好"\] 。 数组长度：1-2048 | | model | 是 | String | 向量化模型名称。 | 请求示例： ``` { "model": "my-embedding-model", "input": "你好" } ``` **响应体参数** 表12响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | data | Array of [Embedding] objects | 向量化结果。 | | model | String | 向量化模型名称。 | | object | String | 固定值'list'。 | | usage | [usage] object | 每次请求的用量统计。 | 表13Embedding | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | 向量在向量列表中的排序。 | | embedding | Array of numbers | 向量数组（Float类型）。 | | object | String | 固定值'embedding'。 | 表14usage | 参数 | 参数类型 | 描述 | |:---|:---|:---| | prompt_tokens | Integer | 提问包含的token数。 | | total_tokens | Integer | 提问包含的token数。 | 响应示例： ``` { "data": [ { "index": 0, "embedding": [ 0.02513289265334606, -0.017512470483779907, -0.029955564066767693, ... ], "object": "embedding" } ], "usage": { "prompt_tokens": 5, "total_tokens": 5 }, "model": "my-embedding-model", "object": "list" } ``` #### 文本排序（Rerank）API规范 **接口格式** 类型：POST 协议：HTTP/HTTPS **请求体参数** 表15请求体参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 是 | String | 原始请求问题，基于该问题对候选文本进行排序。 | | top_n | 是 | Integer | 返回排序靠前的n个结果。 | | docs | 是 | Array of strings | 候选文本，文件大小限制为512M以内。 | | model | 是 | String | 排序模型名称。 | 请求示例： ``` { "model": "my-rerank-model", "query": "请问AI原生应用引擎提供了什么能力？", "docs": ["AI原生应用引擎提供了应用开发、模型网关等能力。", "AI原生应用引擎正在逐步完善、提高竞争力。"], "top_n": 3 } ``` **响应体参数** 表16响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | model | String | 排序模型名称。 | | usage | [usage] object | 每次请求的用量统计。 | | results | Array of [RankDocument] objects | 排序结果 | 表17usage | 参数 | 参数类型 | 描述 | |:---|:---|:---| | prompt_tokens | Integer | 提问包含的token数。 | | total_tokens | Integer | 提问包含的token数。 | 表18RankDocument | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | 文本排序后对应的序号。 | | document | [Document] object | 文本 | | relevance_score | Number | 文本的排序分数。 | 表19Document | 参数 | 参数类型 | 描述 | |:---|:---|:---| | text | String | 文本内容。 | 响应示例： ``` { "model": "my-rerank-model", "usage": { "prompt_tokens": 5, "total_tokens": 5 }, "results": [ { "index": 0, "document": {"text": "AI原生应用引擎提供了应用开发、模型网关等能力。"}, "relevance_score": 0.9 }, { "index": 1, "document": {"text": "AI原生应用引擎正在逐步完善、提高竞争力。"}, "relevance_score": 0.5 } ] } ``` #### 图像理解API规范 **接口格式** 类型：POST 协议：HTTP/HTTPS **请求体参数** 表20请求体参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | messages | 是 | Array of [ChatCompletionRequestMessage] objects | 图像理解对话消息体类。 | | model | 是 | String | 图像理解对话使用的模型名称。 | | frequency_penalty | 否 | Number | 介于-2.0和2.0之间的数字。 正值会根据文本中新Token的现有频率对其进行惩罚，从而降低模型重复相同行的可能性。 **最小值：-2** **最大值：2** **缺省值：0** | | logprobs | 否 | boolean | 是否返回输出Token的对数概率。 | | top_logprobs | 否 | Integer | 指定在每一步生成时，返回模型最大概率的候选Token个数。 取值范围：\[0,5\] 仅当**logprobs**为true时生效。 | | max_tokens | 否 | Integer | 返回体允许的最大token数。 | | presence_penalty | 否 | Number | 介于-2.0和2.0之间的数字。 正值会根据它们是否出现在文本中来惩罚得到新的Token，从而增加模型谈论新主题的可能性。 **最小值：-2** **最大值：2** **缺省值：0** | | n | 否 | Integer | 默认值为1。 生成响应的个数，取值范围是1-4。对于需要生成多个响应的场景（如创意写作、广告文案等），可以设置较大的n值。 | | stream | 否 | Boolean | 布尔类型。 设为true时，返回结果为流式。 设为false时，返回结果为JSON格式结构化数据。 **缺省值：false** | | seed | 否 | Integer | 设置seed参数会使文本生成过程更具有确定性，通常用于使模型每次运行的结果一致。 在每次模型调用时传入相同的seed值（由您指定），并保持其他参数不变，模型将尽可能返回相同的结果。 取值范围：0到2^31^−1。 | | temperature | 否 | Number | 较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定。 **最小值：0** **最大值：2** **缺省值：1** | | top_p | 否 | Number | 影响输出文本的多样性，取值越大，生成文本的多样性越强。 **最小值：0.0** **最大值：1.0** **缺省值：1** | 表21ChatCompletionRequestMessage | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 是 | String | 消息体对应的角色。 如果是系统则为system。 如果是用户则为user。 枚举值： - **system** - **user** | | content | 是 | String | 消息具体内容。 | | name | 否 | String | 对话参与者的可选名称，提供给模型信息以区分相同角色的不同对话参与者。 | 请求示例： ``` { "model": "model-img2text", "messages": [ { "role": "system", "content": " You are a helpful assistant. " }, { "role": "user", "content": [ { "type": "text", "text": "图里面有什么" }, { "type": "image_url", "image_url": { "url": "一个图片链接" } } ], } ], "max_tokens": 20, "presence_penalty": 1.2, "frequency_penalty": 1.0, "temperature": 0.5, "top_p": 0.95, "stream": false } ``` **响应体参数** 表22响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 图像理解文本对话唯一标识符。 | | choices | Array of [表23 ChatNonStreamingChoice] objects | 返回体列表。 如果'n'大于1，则结果为多个。 | | created | long | 问答发生的时间（格式为时间戳）。 | | model | String | 图像理解文本对话使用的模型名称。 | | object | String | 固定值'chat.completion'。 | | usage | [CompletionUsage] object | 图像理解文本对话用量统计。 | 表23ChatNonStreamingChoice | 参数 | 参数类型 | 描述 | |:---|:---|:---| | index | Integer | 返回多个choices时，每个choice对应的顺序。 | | message | [表24 ChatMessageResponse] object | 模型服务返回的具体消息体内容。 | | finish_reason | String | 返回结束的原因。 - **stop：**模型达到自然停止点或提供的停止序列。 - **length：**达到请求中指定的最大令牌数。 - **content_filter：**由于内容过滤器的标志而省略了内容。 - **tool_calls：**模型选择了某个工具。 枚举值： - **stop** - **length** - **content_filter** - **tool_calls** | 表24ChatMessageResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | content | String | 返回消息体的内容，与tool_calls二选一。 | | role | String | 返回消息体的角色。 枚举值：**assistant** | | tool_calls | Array of [ToolCall] objects | 工具调用消息，与content二选一。 | | audio | ChatMessageAudio | 聊天信息中的音频部分。 | | reasoningContent | String | 用于展示模型的推理过程，帮助用户理解模型的决策依据。 | 表25ToolCall | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 工具调用唯一标识符。 | | type | String | 工具类型，当前仅支持function。 | | function | [CallFunction] Object | 调用函数的详细信息。 | 表26CallFunction | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | 函数名。 | | arguments | String | 调用函数的参数，JSON格式。 | 表27CompletionUsage | 参数 | 参数类型 | 描述 | |:---|:---|:---| | completion_tokens | Integer | 回答包含的token数。 | | prompt_tokens | Integer | 提问包含的token数。 | | total_tokens | Integer | 提问+回答token总数。 | **响应示例** ``` { "choices": [ { "delta": { "role": "assistant", "content": "图像整体呈现出简洁、抽象的风格，主要内容是一个灰色的圆形头像轮廓。" }, "finish_reason": "stop", "index": 0 } ], "created": 1753965925754, "id": "model-img2text", "object": "chat.completions", "usage": { "prompt_tokens": 142, "completion_tokens": 118, "total_tokens": 260 }, "request_id": "xxx" } ```