BYO-LLM

本文说明如何用 OpenAI API 兼容方式接入自研、微调或私有化部署的大语言模型。页名 BYO-LLM。平台转发请求并按能力配置调用；模型回复由企业的模型服务生成。

这里的 QPS、并发和超时是模型服务自身的限制，不是开放接口的访问频次。

快速阅读

优先提供 POST /v1/chat/completions。鉴权使用 Authorization: Bearer <API_KEY>。若接口不需要鉴权，必须书面说明。

上下文长度和最大输出长度在平台中填纯数字。例如 128K 填 128000。

非兼容接口需要另附完整接口文档，适配范围以联调评估为准。

阅读地图

内容	章节
企业要提交的服务信息	配置项：模型服务信息
平台添加 `OpenAI-API-compatible` 时的能力开关	配置项：平台能力配置
请求和响应长什么样	请求与响应
呼入 / 外呼机器人与对话分析何时真的调到该模型	生效、验收

配置项

模型服务信息

参数	必填	填写要求
API endpoint / 接入点	是	完整调用地址，例如 `https://example.com/v1/chat/completions`
API endpoint URL / 基础地址	是	去掉 `/chat/completions`。上例填 `https://example.com/v1`
API Key / 鉴权密钥	是	用于 `Authorization: Bearer <API_KEY>`。无需鉴权时明确说明
model / 模型名称	是	服务实际识别的模型 ID，例如 `qwen3-8b`
endpoint model name / Endpoint 模型名称	否	仅当服务要求在 endpoint 配置里单独声明时填写
OpenAI API-compatible / 接口协议	是	优先 `/v1/chat/completions`。非兼容接口另附文档
HTTP Method / 请求方法	是	通常为 `POST`
HTTP Headers / 请求头	是	至少 `Authorization: Bearer <API_KEY>`、`Content-Type: application/json`
Request Body / 请求体参数	是	说明 `model`、`messages`、`temperature`、`top_p`、`max_tokens`、`stream`、`stream_options` 的支持情况
Response Schema / 返回体格式	是	回复内容、Token 用量、错误码、错误信息所在字段
stream / 流式输出	是	是否支持 `stream=true`，以及分隔符
Context Length / 上下文长度	是	纯数字，例如 `128000`
max_tokens / 最大输出长度	是	单次响应最大输出 Token 数
Sampling Parameters / 生成参数	否	`temperature`、`top_p`、`presence_penalty`、`frequency_penalty` 的默认值或限制
Network Access / 网络访问方式	是	公网、专线、VPN 或内网白名单
IP Allowlist / IP 白名单	视网络	限制来源时提供开通要求
Rate Limit / Timeout / 限流与超时	否	模型服务的 QPS、并发、超时和额度

平台接入配置示例：

{
  "provider": "OpenAI-API-compatible",
  "modelType": "LLM",
  "apiEndpointUrl": "https://example.com/v1",
  "apiKey": "sk-xxxx",
  "model": "qwen3-8b",
  "contextLength": 128000,
  "maxTokens": 8192,
  "stream": true
}

平台能力配置

添加 OpenAI-API-compatible 模型时确认：

配置项	必填	配置要求
Model Type / 模型类型	是	`LLM`
model / 模型名称	是	服务实际识别的模型 ID
Model Display Name / 模型显示名称	否	便于业务识别的展示名
API Key / 鉴权密钥	是	调用时生成 `Authorization: Bearer <API_KEY>`
API endpoint URL / 基础地址	是	`/chat/completions` 前的地址，例如 `https://example.com/v1`
endpoint model name / API endpoint 中的模型名称	否	无特殊要求时可不填，或与模型名称一致
Completion mode / 完成模式	是	`对话`
Context Length / 模型上下文长度	是	纯数字，例如 `128000`
max_tokens / 最大 token 上限	是	模型允许的最大输出 Token 数
Agent Thought / 推理能力	是	支持推理或思考选 `支持`，否则 `不支持`
Function calling / 工具调用	是	支持时选 `Tool Call`；旧版接口可选 `Function Call`；不支持选 `不支持`
Stream function calling / 流式工具调用	是	支持选 `支持`，否则 `不支持`
Vision / 视觉输入	是	支持图片等视觉输入选 `支持`，纯文本选 `不支持`
Structured Output / 结构化输出	是	支持 JSON 等结构化输出选 `支持`，否则 `不支持`
Stream mode auth / 流式鉴权	否	无特殊要求选 `不使用`
Stream delimiter / 流模式返回结果的分隔符	否	按服务协议填写，默认可使用 `\n\n`

能力开关必须与模型服务真实能力一致。打开工具调用或视觉，但服务不支持时，联调会在对应请求上失败。

配置来源：企业提交上表；平台写入模型配置；呼入机器人、外呼机器人或对话分析选择该模型后才发起调用。

请求与响应

请求示例：

POST /v1/chat/completions HTTP/1.1
Host: example.com
Authorization: Bearer sk-xxxx
Content-Type: application/json

{
  "model": "qwen3-8b",
  "messages": [
    {
      "role": "user",
      "content": "请总结这通会话的主要问题"
    }
  ],
  "temperature": 0.7,
  "top_p": 0.9,
  "max_tokens": 1024,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

非流式响应需能取到回复内容。支持用量统计时返回 usage。

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "本通会话主要围绕客户咨询订单状态展开，客服已完成查询并告知预计送达时间。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 36,
    "total_tokens": 164
  }
}

stream=true 时按服务约定的分隔符持续返回，例如：

data: {"choices":[{"delta":{"content":"本通"},"index":0}]}

data: {"choices":[{"delta":{"content":"会话主要围绕客户咨询订单状态展开。"},"index":0}]}

data: [DONE]

生效

地址、密钥、模型名称和网络白名单可用。
平台能力开关与服务能力一致，上下文和 max_tokens 已填纯数字。
呼入机器人、外呼机器人或对话分析实际选中该模型。
服务返回 choices 中的回复；流式时分隔符与平台配置一致。

地址、密钥、模型名称或协议变更后同步改平台配置。内网部署时先完成网络打通。模型效果、时延、稳定性和费用取决于该模型服务。

验收

测试问题能打通鉴权，并取到回复文本。
messages、stream、max_tokens 与服务要求一致。
流式输出的分隔符与「Stream delimiter」一致。
鉴权失败、模型不存在、限流、超时能从错误码和错误信息区分。
对话分析若要求 JSON，先确认 Structured Output 为 支持，且返回里能稳定取到该结构。
按业务峰值核对模型服务自己的 QPS、并发和超时，不要用开放接口频次页的默认值代替。