1. 概览

当您需要在 CTICloud 中使用自研、微调或私有化部署的大语言模型时，可以通过 BYO-LLM（Bring Your Own LLM）方式接入。接入完成后，模型可用于对话机器人、对话分析等场景。

CTICloud 将作为 AI 应用与模型服务之间的调用平台，负责模型资源管理、能力配置、请求转发与联调验证；您的模型服务负责根据接口请求生成模型回复。

• 核心价值：通过 OpenAI API 兼容协议接入自有模型，降低模型迁移和适配成本。
• 技术栈支持：推荐提供 /v1/chat/completions 兼容接口，支持流式输出、工具调用、视觉输入、结构化输出等能力配置。
• 灵活配置：支持自定义模型名称、上下文长度、最大输出长度、鉴权密钥、限流与网络访问方式。

2. 全流程概述

2.1 自有大模型接入完整流程

┌───────────────────────────────────────────────┐
│              BYO-LLM 接入全流程                │
└───────────────────────────────────────────────┘

🚀 步骤 1：模型服务准备
├── 部署客户自有大模型服务，并确保服务可被 CTICloud 网络环境访问。
└── 推荐提供 OpenAI API 兼容接口，如 /v1/chat/completions。

⚙️ 步骤 2：模型接入配置
├── 向 CTICloud 提供模型调用地址、API Key、模型名称等接入信息。
└── 配置上下文长度、最大输出长度、流式输出、工具调用等模型能力。

🔍 步骤 3：接口联调验证
├── CTICloud 发起测试请求，验证连通性、鉴权、响应格式与流式输出。
└── 根据联调结果调整接口协议、参数字段或网络白名单。

✅ 步骤 4：业务场景启用
├── 验证通过后，在对话机器人、对话分析等场景中选择该模型。
└── 根据业务峰值确认 QPS、并发数、超时时间和稳定性表现。

3. BYO-LLM 接入说明

为实现自有大模型与 CTICloud 的对接，整体流程分为两个阶段：

• 模型服务准备：您需完成自有模型服务部署，并确保满足以下要求
  • 接口协议：优先支持 OpenAI API 兼容协议，推荐提供 /v1/chat/completions 接口
  • 鉴权方式：支持通过 Authorization: Bearer <API_KEY> 等方式进行调用鉴权
  • 请求处理：能够正确接收 model、messages、temperature、top_p、max_tokens、stream 等请求参数
  • 响应格式：能够返回模型回复内容，建议同步返回 Token 用量、错误码和错误信息
  • 接口能力：如支持流式输出、工具调用、视觉输入、结构化输出或推理能力，请在接入时同步说明
• CTICloud 平台接入配置：模型服务准备完成后，向 CTICloud 提供以下信息用于平台侧接入配置
  • 模型调用地址
  • API Key
  • 模型名称
  • 上下文长度与最大输出长度
  • 网络访问方式、IP 白名单、限流与超时说明

CTICloud 平台完成配置后，将在对话机器人、对话分析等业务过程中调用客户模型服务，最终实现自有大模型能力在 CTICloud 平台中的使用。

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

3.1 模型服务信息

该部分说明接入 BYO-LLM 时需要提供的模型服务信息。CTICloud 将根据以下信息完成模型注册、接口调用和联调验证。

3.2 平台配置参数

该部分说明 CTICloud 添加 OpenAI-API-compatible 模型时需要确认的能力配置。

上下文长度和最大输出长度请填写纯数字。例如模型上下文长度为 128K，平台中填写 128000。

4. 业务场景说明

4.1 对话机器人：使用自有模型生成回复

在对话机器人场景中，CTICloud 会将用户输入、上下文配置和模型参数发送至自有大模型服务。模型服务返回回复后，平台将结果用于机器人对话流程。

该场景建议重点关注：

• 模型回复稳定性和首字响应速度。
• 是否支持流式输出，便于降低用户等待时间。
• 最大输出长度是否满足业务话术要求。
• 限流、并发数和超时时间是否满足业务峰值。

4.2 对话分析：使用自有模型完成内容理解

在对话分析场景中，CTICloud 可调用自有大模型对会话文本进行理解和分析，例如摘要生成、意图识别、质检标签提取等。

该场景建议重点关注：

• 模型上下文长度是否能够覆盖待分析的会话内容。
• 响应体中是否能稳定返回结构化或半结构化结果。
• 若需要 JSON 等固定格式输出，需确认模型是否支持结构化输出能力。
• 批量分析时需提前确认 QPS、并发数和调用额度限制。

5. 接口请求与响应示例

5.1 请求示例（CTICloud->模型服务）

OpenAI API 兼容接口可参考以下请求格式。实际字段请以客户模型服务支持情况为准。

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
  }
}

5.2 响应示例（模型服务->CTICloud）

非流式响应需返回模型回复内容。若接口支持 Token 用量统计，建议同步返回用量字段，便于后续排查和统计。

{
  "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
  }
}

5.3 流式响应示例（模型服务->CTICloud）

若模型服务支持 stream=true，需提供稳定的流式返回协议和分隔符。OpenAI API 兼容流式响应可参考以下格式：

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

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

data: [DONE]

6. 联调验证与注意事项

6.1 联调验证

模型配置完成后，CTICloud 会使用客户提供的测试问题验证接口连通性、鉴权、响应格式和流式输出。联调时重点确认：

• 请求地址、鉴权密钥和模型名称是否正确。
• messages、stream、max_tokens 等请求字段是否与模型服务要求一致。
• 响应体中是否能稳定获取模型回复内容。
• 流式输出是否支持 stream=true，以及分隔符是否与平台配置一致。
• 错误码和错误信息是否能清晰返回，便于定位鉴权失败、模型不存在、限流或超时等问题。

6.2 接入前检查

提交接入前，请确认：

• 模型服务已部署完成，且接口可正常调用。
• 鉴权凭证有效，并具备目标模型的调用权限。
• CTICloud 可访问模型服务所在网络。
• 模型接口协议、请求参数、响应结构和错误格式已明确。
• 模型上下文长度、最大输出长度、并发限制和 QPS 限制已明确。
• 如需流式输出，模型服务已支持 stream=true 并提供稳定的流式返回。

6.3 注意事项

• 客户需确保提供的鉴权凭证合法有效，并自行管理凭证权限和有效期。
• 模型服务部署在客户内网时，需提前完成网络打通和访问白名单配置。
• 非 OpenAI API 兼容接口需单独评估适配工作量。
• 模型效果、响应速度、稳定性和调用费用取决于客户提供的模型服务。
• 模型地址、鉴权方式、模型名称或接口协议变更后，需同步更新平台配置。