j9九游会登录/ 应用平台 appstage/ / / / 模型服务api接入接口规范

更新时间：2025-08-04 gmt 08:00

模型服务api接入接口规范-j9九游会登录

当前模型网关支持文本对话（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。

表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	候选文本，文件大小限制为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	排序结果

**表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
     }
   ]
}

图像理解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³¹−1。
temperature	否	number	较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定。最小值：0 最大值：2 缺省值：1
top_p	否	number	影响输出文本的多样性，取值越大，生成文本的多样性越强。最小值：0.0 最大值：1.0 缺省值：1

**表21** chatcompletionrequestmessage
参数	是否必选	参数类型	描述
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	图像理解文本对话用量统计。

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

**表24** chatmessageresponse
参数	参数类型	描述
content	string	返回消息体的内容，与tool_calls二选一。
role	string	返回消息体的角色。枚举值：assistant
tool_calls	array of toolcall objects	工具调用消息，与content二选一。
audio	chatmessageaudio	聊天信息中的音频部分。
reasoningcontent	string	用于展示模型的推理过程，帮助用户理解模型的决策依据。

**表25** toolcall
参数	参数类型	描述
id	string	工具调用唯一标识符。
type	string	工具类型，当前仅支持function。
function	callfunction object	调用函数的详细信息。

**表26** callfunction
参数	参数类型	描述
name	string	函数名。
arguments	string	调用函数的参数，json格式。

**表27** completionusage
参数	参数类型	描述
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"
}

父主题：

上一篇：接入模型服务

下一篇：调测模型服务

意见反馈

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

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

系统繁忙，请稍后重试

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

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

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

字符长度不能超过500

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

模型服务api接入接口规范-j9九游会登录

文本对话（chat）api规范

文本向量化（embeddings）api规范

文本排序（rerank）api规范

图像理解api规范

相关文档

意见反馈

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