文档首页/ 应用平台 AppStage/ AI原生应用引擎用户指南/ 管理模型/ 模型API接入接口规范

更新时间：2024-12-06 GMT+08:00

模型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<String,Integer>	该参数接受一个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。

表2 ChatCompletionRequestMessage
参数	是否必选	参数类型	描述
role	是	String	消息体对应的角色。如果是系统则为system。如果是用户则为user。枚举值： system user
content	是	String	消息具体内容。
name	否	String	对话参与者的可选名称，提供给模型信息以区分相同角色的不同对话参与者。

表3 FunctionCallTool
参数	是否必选	参数类型	描述
type	否	String	调用工具类型，目前仅支持function。
function	否	function object	仅当工具类型为function时补充。

表4 function
参数	是否必选	参数类型	描述
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	文本对话用量统计。

表6 choices
参数	参数类型	描述
index	Integer	返回多个choices时，每个choice对应的顺序。
message	ChatCompletionResponseMessage object	模型服务返回的具体消息体内容。
finish_reason	String	返回结束的原因。 stop：模型达到自然停止点或提供的停止序列。 length：达到请求中指定的最大令牌数。 content_filter：由于内容过滤器的标志而省略了内容。 tool_calls：模型选择了某个工具。枚举值： stop length content_filter tool_calls

表7 ChatCompletionResponseMessage
参数	参数类型	描述
content	String	返回消息体的内容，与tool_calls二选一。
role	String	返回消息体的角色。枚举值： assistant
tool_calls	Array of ToolCall objects	工具调用消息，与content二选一。

表8 ToolCall
参数	参数类型	描述
id	String	工具调用唯一标识符。
type	String	工具类型，当前仅支持function。
function	CallFunction Object	调用函数的详细信息。

表9 CallFunction
参数	参数类型	描述
name	String	函数名。
arguments	String	调用函数的参数，Json格式。

**表10** CompletionUsage
参数	参数类型	描述
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	每次请求的用量统计。

**表13** Embedding
参数	参数类型	描述
index	Integer	向量在向量列表中的排序。
embedding	Array of numbers	向量数组（Float类型）。
object	String	固定值‘embedding’。

**表14** usage
参数	参数类型	描述
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	候选文本。
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	排序结果

**表17** usage
参数	参数类型	描述
prompt_tokens	Integer	提问包含的token数。
total_tokens	Integer	提问包含的token数。

**表18** RankDocument
参数	参数类型	描述
index	Integer	文本排序后对应的序号。
document	Document object	文本
relevance_score	Number	文本的排序分数。

**表19** Document
参数	参数类型	描述
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
     }
   ]
}

父主题： 管理模型

上一篇：收藏平台资产中心的模型

下一篇：如何对模型供应商提供的模型服务设置鉴权

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问

模型API接入接口规范

文本对话（Chat）API规范

文本向量化（Embeddings）API规范

文本排序（Rerank）API规范

相关文档

意见反馈

文档内容是否对您有帮助？

7*24

备案

专业服务

退订

建议反馈

售前咨询热线