towncharlie[docs] 修复文档错误，更新Coordinator端口相关说明

738336bf创建于 17 天前历史提交

业务接口

OpenAI Chat Completion 接口

接口功能

提供与 OpenAI v1/chat/completions 兼容的对话生成入口，用于多轮对话、角色设定与上下文续写。

接口格式

请求类型：POST URL：http(s)://{CoordinatorIP}:{推理端口}/v1/chat/completions

说明

{CoordinatorIP}：Coordinator 服务部署机器的 IP 或域名，取值来自配置 api_config.coordinator_api_host（默认127.0.0.1），参考deployer/user_config.json取值或实际运行时节点IP。
{推理端口}：内部端口取值来自于配置项api_config.coordinator_api_infer_port（默认 1025），对外绑定端口由部署配置deployer/deployment/coordinator_init.yaml的spec.ports[].nodePort指定（默认 31015）。

请求头：

必选：Content-Type: application/json
可选：{api_key_config.header_name}: {api_key_config.key_prefix}{API_KEY}（默认 Authorization: Bearer {API_KEY}）

请求参数

参数名	类型	说明
model	string	必选；模型名称。
messages	array	必选；对话消息列表。
stream	boolean	可选；是否流式输出，默认为false。 true：流式; false：非流式。

messages参数中的子参数解释如下：

参数名	类型	说明
role	string	必选；角色如下： `system`：系统/规则提示； `user`：用户输入； `assistant`：助手输出。对话中通常以 `system` 作为最高优先级约束，`user` 为问题内容，`assistant` 为历史回答。
content	string	必选；消息内容。

其余OpenAI兼容字段（如max_tokens、temperature等）将透传给后端推理引擎。常用参数说明如下：

参数	类型	说明
max_tokens	integer	最大生成token数上限。
temperature	number	采样温度，温度越大输出结果越随机（常用 0~1），温度过大可能导致输出不稳定。
top_p	number	nucleus采样阈值（0~1），与`temperature` 参数同时使用时通常取其一。
presence_penalty	number	话题惩罚项，鼓励引入新内容；取值区间依后端实现。
frequency_penalty	number	频率惩罚项，降低重复内容；取值区间依后端实现。
stop	string/array	停止词，匹配后提前结束生成。

说明

未被后端推理引擎支持的字段会被忽略或降级处理，具体能力以实际模型与后端版本为准。

使用样例

流式使用样例：

curl -N -X POST "http://{CoordinatorIP}:{推理端口}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "model": "qwen3",
    "messages": [
      { "role": "user", "content": "Hello there!" }
    ],
    "stream": true
  }'

非流式使用样例：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "model": "qwen3",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Hi!" }
    ],
    "temperature": 0.7
  }'

响应样例

流式响应样例：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"content":"Hey there! "},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"content":"Great to see you. "},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"content":"How can I help today?"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

非流式响应示例：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1765856304,
  "model": "qwen3",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hey there! Great to see you—how can I help today?" },
      "finish_reason": "stop"
    }
  ]
}

输出说明

流式响应参数说明：

流式响应为SSE事件流，每行以data:开头，data: [DONE]表示结束。data:后的JSON结构如下：

参数名	类型	说明
id	string	本次请求ID。
object	string	返回对象类型：`chat.completion.chunk`。
created	integer	创建时间戳（秒）。
model	string	模型名称。
choices	array	增量结果列表。
choices[].index	integer	序号。
choices[].delta	object	增量内容。
choices[].delta.role	string	仅首包可能返回`assistant`。
choices[].delta.content	string	生成增量文本。
choices[].finish_reason	string/null	结束原因，未结束时为`null`。

非流式响应参数说明：

参数名	类型	说明
id	string	本次请求ID。
object	string	返回对象类型：`chat.completion`。
created	integer	创建时间戳（秒）。
model	string	模型名称。
choices	array	生成结果列表。
choices[].index	integer	序号。
choices[].message	object	生成消息。
choices[].message.role	string	角色，固定为`assistant`。
choices[].message.content	string	生成内容。
choices[].finish_reason	string/null	结束原因，如`stop`、`length`等。

Anthropic Messages 接口

接口功能

提供与 Anthropic Messages API 兼容的对话生成入口，支持多模态图片输入、工具调用、思考链（thinking）内容块。请求由 Coordinator 透明转发至 vLLM 后端引擎，由 vLLM 处理完整的 Anthropic 协议。仅 vLLM 后端模式可用。

接口格式

请求类型：POST URL：http(s)://{CoordinatorIP}:{推理端口}/v1/messages

说明

{CoordinatorIP}：Coordinator 服务部署机器的 IP 或域名，取值来自配置 api_config.coordinator_api_host（默认 127.0.0.1），参考 deployer/user_config.json 取值或实际运行时节点IP。
{推理端口}：内部端口取值来自于配置项 api_config.coordinator_api_infer_port（默认 1025），对外绑定端口由部署配置 deployer/deployment/coordinator_init.yaml 的 spec.ports[].nodePort 指定（默认 31015）。

请求头：

必选：Content-Type: application/json
可选：{api_key_config.header_name}: {api_key_config.key_prefix}{API_KEY}（默认 Authorization: Bearer {API_KEY}）；也支持标准 Anthropic 格式 x-api-key: {API_KEY}

请求参数

参数名	类型	说明
model	string	必选；模型名称。
messages	array	必选；对话消息列表，每条消息包含 `role`（`user` 或 `assistant`）和 `content`（字符串或内容块数组）。
max_tokens	integer	必选；最大生成 token 数。
stream	boolean	可选；是否流式输出（SSE），默认为 `false`。
system	string/array	可选；系统提示词，支持字符串或内容块数组格式。
stop_sequences	array	可选；停止序列列表。
temperature	number	可选；采样温度（0~1）。
top_p	number	可选；nucleus 采样阈值。
top_k	integer	可选；top-k 采样参数。
tools	array	可选；工具定义列表，每条工具包含 `name`、`description`、`input_schema`。
tool_choice	object	可选；工具选择策略，`type` 取值：`auto`、`any`、`tool`、`none`。

使用样例

基本文本对话（非流式）：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {API_KEY}" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ],
    "max_tokens": 100
  }'

流式对话：

curl -N -X POST "http://{CoordinatorIP}:{推理端口}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {API_KEY}" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      { "role": "user", "content": "Explain quantum computing in simple terms." }
    ],
    "max_tokens": 200,
    "stream": true
  }'

带系统提示词：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {API_KEY}" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      { "role": "user", "content": "What is the weather?" }
    ],
    "max_tokens": 100,
    "system": "You are a helpful weather assistant."
  }'

带工具调用：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {API_KEY}" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      { "role": "user", "content": "What is the weather in Beijing?" }
    ],
    "max_tokens": 100,
    "tools": [
      { "name": "get_weather", "description": "Get current weather", "input_schema": { "type": "object" } }
    ],
    "tool_choice": { "type": "auto" }
  }'

响应样例

非流式响应样例：

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Hello! How can I help you today?" }
  ],
  "model": "qwen3-8b",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 8
  }
}

流式响应样例（SSE 事件流）：

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"qwen3-8b","usage":{"input_tokens":10}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello! "}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"How can I help?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":8}}

event: message_stop
data: {"type":"message_stop"}

data: [DONE]

输出说明

非流式响应参数说明：

参数名	类型	说明
id	string	本次请求 ID。
type	string	返回对象类型：`message`。
role	string	角色，固定为 `assistant`。
content	array	内容块列表。
content[].type	string	内容块类型：`text`、`tool_use`、`thinking` 等。
content[].text	string	文本内容（当 type 为 `text` 时）。
model	string	模型名称。
stop_reason	string	结束原因：`end_turn`（正常结束）、`max_tokens`（达到上限）、`tool_use`（工具调用）。
usage	object	Token 统计，包含 `input_tokens`、`output_tokens`。

流式响应事件类型说明：

事件类型	说明
`message_start`	消息开始，包含元数据和初始 usage。
`content_block_start`	内容块开始，标记一个新的 text / tool_use / thinking 块。
`content_block_delta`	内容块增量，携带 `text_delta`、`input_json_delta`、`thinking_delta` 等。
`content_block_stop`	内容块结束。
`message_delta`	消息增量，包含 `stop_reason` 和最终 usage。
`message_stop`	消息结束。

Anthropic Count Tokens 接口

接口功能

提供与 Anthropic messages/count_tokens 兼容的 Token 计数入口，用于预估输入消息的 Token 消耗。请求由 Coordinator 透明转发至 vLLM 后端引擎。仅 vLLM 后端模式可用。

接口格式

请求类型：POST URL：http(s)://{CoordinatorIP}:{推理端口}/v1/messages/count_tokens

请求头：与 /v1/messages 一致。

请求参数

参数名	类型	说明
model	string	必选；模型名称。
messages	array	必选；消息列表，格式同 `/v1/messages`。
system	string/array	可选；系统提示词。
tools	array	可选；工具定义。
tool_choice	object	可选；工具选择策略。

使用样例

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {API_KEY}" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

响应样例

{
  "input_tokens": 10,
  "context_management": {
    "original_input_tokens": 10
  }
}

输出说明

参数名	类型	说明
input_tokens	integer	输入 Token 数量。
context_management	object	上下文管理信息。
context_management.original_input_tokens	integer	原始输入 Token 数量。

OpenAI Completion 接口

接口功能

OpenAI Completion 兼容接口，支持文本补全与结果采样。

接口格式

请求类型：POST URL：http(s)://{CoordinatorIP}:{推理端口}/v1/completions

说明

{CoordinatorIP}：Coordinator 服务部署机器的 IP 或域名，取值来自配置 api_config.coordinator_api_host（默认 127.0.0.1），参考 deployer/user_config.json 取值或实际运行时节点IP。
{推理端口}：内部端口取值来自于配置项 api_config.coordinator_api_infer_port（默认 1025），对外绑定端口由部署配置 deployer/deployment/coordinator_init.yaml 的 spec.ports[].nodePort 指定（默认 31015）。

请求头：

必选：Content-Type: application/json
可选：{api_key_config.header_name}: {api_key_config.key_prefix}{API_KEY}（默认 Authorization: Bearer {API_KEY}）

请求参数

参数名	类型	说明
model	string	必选；模型名称。
prompt	string/array	必选；提示词。
stream	boolean	可选；是否流式输出，默认为false。 true：流式; false：非流式。

其余OpenAI兼容字段（如max_tokens、temperature等）将透传给后端推理引擎。常用字段说明同上，若后端不支持部分字段将被忽略或降级处理。

使用样例

流式使用样例：

curl -N -X POST "http://{CoordinatorIP}:{推理端口}/v1/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "model": "qwen3",
    "prompt": "Hello!",
    "stream": true
  }'

非流式使用样例：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "model": "qwen3",
    "prompt": "Hi!",
    "max_tokens": 64,
    "temperature": 0.7
  }'

响应示例

流式响应样例：

data: {"id":"cmpl-xxx-0","object":"text_completion","created":1765856304,"model":"qwen3","choices":[{"index":0,"text":"Hey there! ","finish_reason":null}]}

data: {"id":"cmpl-xxx-0","object":"text_completion","created":1765856304,"model":"qwen3","choices":[{"index":0,"text":"Lovely to hear from you—","finish_reason":null}]}

data: {"id":"cmpl-xxx-0","object":"text_completion","created":1765856304,"model":"qwen3","choices":[{"index":0,"text":"what would you like to do today?","finish_reason":null}]}

data: {"id":"cmpl-xxx-0","object":"text_completion","created":1765856304,"model":"qwen3","choices":[{"index":0,"text":"","finish_reason":"stop"}]}

data: [DONE]

非流式响应样例（非流式）：

{
  "id": "cmpl-xxx-0",
  "object": "text_completion",
  "created": 1765856304,
  "model": "qwen3",
  "choices": [
    { "index": 0, "text": "Hey there! Lovely to hear from you—what would you like to do today?", "finish_reason": "stop" }
  ]
}

输出说明

流式响应参数说明：

流式响应为SSE事件流，每行以data: 开头，data: [DONE]表示结束。data:后的JSON结构如下：

参数名	类型	说明
id	string	本次请求ID。
object	string	返回对象类型：`text_completion`。
created	integer	创建时间戳（秒）。
model	string	模型名称。
choices	array	增量结果列表。
choices[].index	integer	序号。
choices[].text	string	生成增量文本。
choices[].finish_reason	string/null	结束原因，未结束时为`null`。

非流式响应参数说明：

参数名	类型	说明
id	string	本次请求ID。
object	string	返回对象类型：`text_completion`。
created	integer	创建时间戳（秒）。
model	string	模型名称。
choices	array	生成结果列表。
choices[].index	integer	序号。
choices[].text	string	生成文本。
choices[].finish_reason	string/null	结束原因，如`stop`、`length`等。

MetaServer转发接口（内部接口）

接口功能

仅在PD/CDP分离部署场景使用，用于D节点将请求转发至P节点。

接口格式

请求类型：POST URL：http(s)://{CoordinatorIP}:{推理端口}/v1/metaserver

说明

{CoordinatorIP}：Coordinator 服务部署机器的 IP 或域名，取值来自配置 api_config.coordinator_api_host（默认 127.0.0.1），参考 deployer/user_config.json 取值或实际运行时节点IP。
{推理端口}：内部端口取值来自于配置项 api_config.coordinator_api_infer_port（默认 1025），对外绑定端口由部署配置 deployer/deployment/coordinator_init.yaml 的 spec.ports[].nodePort 指定（默认 31015）。

请求头：

必选：Content-Type: application/json
可选：无

请求参数

参数	类型	说明
`model`	string	必选；模型名称，透传至目标节点。
`messages`	array	与 `prompt` 二选一；Chat输入。
`prompt`	string	与 `messages` 二选一；Completion 输入。
`stream`	boolean	可选；是否流式返回，透传至目标节点。
`kv_transfer_params`	object	必选；转发控制参数。
`kv_transfer_params.request_id`	string	必选；请求标识，用于跨节点跟踪与关联。
`kv_transfer_params.do_remote_decode`	boolean	可选；是否在目标节点执行 Decode。
`kv_transfer_params.do_remote_prefill`	boolean	可选；是否在目标节点执行 Prefill。
`kv_transfer_params.remote_engine_id`	string	必选；目标节点引擎 ID。
`kv_transfer_params.remote_host`	string	必选；目标节点地址（IP 或域名）。
`kv_transfer_params.remote_port`	string	必选；目标节点端口。

使用样例

CDP分离场景，D节点触发P节点Prefill：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/metaserver" \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen3",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false,
  "kv_transfer_params": {
    "request_id": "req-id",
    "do_remote_decode": false,
    "do_remote_prefill": true,
    "remote_engine_id": "engine-p-0",
    "remote_host": "10.0.0.12",
    "remote_port": "1000"
  }
}'

PD分离场景，P节点触发D节点Decode：

curl -X POST "http://{CoordinatorIP}:{推理端口}/v1/metaserver" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ],
    "stream": false,
    "kv_transfer_params": {
      "request_id": "req-id",
      "do_remote_decode": true,
      "do_remote_prefill": false,
      "remote_engine_id": "engine-d-0",
      "remote_host": "10.0.0.21",
      "remote_port": "1001"
    }
  }'

响应示例

CDP分离场景，透传P节点响应内容：

{
  "id": "chatcmpl-xxx12",
  "object": "chat.completion",
  "created": 1738828800,
  "model": "qwen3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 7,
    "total_tokens": 13
  }
}

PD分离场景，透传D节点响应内容：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1738828800,
  "model": "qwen3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 9,
    "total_tokens": 17
  }
}

输出说明 该示例为非流式 chat.completion的输出说明：

参数	类型	说明
`id`	string	响应 ID。
`object`	string	响应对象类型，示例为 `chat.completion`。
`created`	integer	响应创建时间（Unix 时间戳）。
`model`	string	实际使用的模型名称。
`choices`	array	生成结果列表。
`choices[].index`	integer	结果序号。
`choices[].message.role`	string	角色，示例为 `assistant`。
`choices[].message.content`	string	生成内容。
`choices[].finish_reason`	string	结束原因，如 `stop`、`length` 等。
`usage`	object	Token 统计信息。
`usage.prompt_tokens`	integer	输入 Token 数量。
`usage.completion_tokens`	integer	输出 Token 数量。
`usage.total_tokens`	integer	总 Token 数量。

模型列表查询接口

接口功能

返回当前AIGW模型配置与实例数量信息。

接口格式

请求类型：GET URL：http(s)://{CoordinatorIP}:{推理端口}/v1/models

说明

{CoordinatorIP}：Coordinator 服务部署机器的 IP 或域名，取值来自配置 api_config.coordinator_api_host（默认 127.0.0.1），参考 deployer/user_config.json 取值或实际运行时节点IP。
{推理端口}：内部端口取值来自于配置项 api_config.coordinator_api_infer_port（默认 1025），对外绑定端口由部署配置 deployer/deployment/coordinator_init.yaml 的 spec.ports[].nodePort 指定（默认 31015）。

请求参数

无

使用样例

curl -X GET "http://{CoordinatorIP}:{推理端口}/v1/models"

响应示例

{
  "object": "list",
  "data": [
    {
      "id": "qwen3",
      "object": "model",
      "owned_by": "motor",
      "p_max_seqlen": 8192,
      "d_max_seqlen": 8192,
      "slo_ttft": 1000,
      "slo_tpot": 50,
      "p_instances_num": 2,
      "d_instances_num": 2,
      "created": 1765856000
    }
  ]
}

输出说明

参数名	类型	说明
object	string	返回对象类型：`list`。
data	array	模型列表。
data[].id	string	模型名称
data[].object	string	返回对象类型。
data[].owned_by	string	模型归属。
data[].p_max_seqlen	integer	P实例最大序列长度。
data[].d_max_seqlen	integer	D实例最大序列长度。
data[].slo_ttft	integer	SLO首token时延（TTFT，单位毫秒）。
data[].slo_tpot	integer	SLO每token时延（TPOT，单位毫秒）。
data[].p_instances_num	integer	P实例数量。
data[].d_instances_num	integer	D实例数量。
data[].created	integer	创建时间戳（秒）。