外部接入：OpenAI 协议与 MCP 网关

什么时候用

需要把平台能力接入外部业务系统、开发框架或 MCP 标准客户端时--无论是用 OpenAI SDK 调模型、调 Agent、做工具调用，还是让 Cursor / Claude Desktop 等 MCP 客户端发现并调用租户注册的 MCP 工具，都需要本章的接入方式。

外部接入分两类：

1. OpenAI 兼容 API：调用模型、模型组、Agent 和工具调用能力，兼容 OpenAI SDK / LangChain / LlamaIndex 等框架。
2. MCP Gateway：让 MCP 标准客户端发现并调用租户注册的上游 MCP Server 工具。

你需要准备

接入前请确认以下前置条件已就绪：

操作步骤

第一部分：OpenAI 兼容 API 接入

第 1 步：确认接入地址与 API Key

OpenAI 兼容 API 的接入信息：

API Key 格式：以 sk-u- 开头，是用户级 API Key（不是管理员登录密码）。创建方式见 管理用户 API Key。

base_url 不要以 / 结尾：https://www.aimatespace.com/openai/v1 正确，https://www.aimatespace.com/openai/v1/ 不推荐（部分 SDK 会拼成 //chat/completions）。

第 2 步：验证连通性（列模型）

用 API Key 调用 GET /openai/v1/models，确认认证和模型权限正常：

curl -s https://www.aimatespace.com/openai/v1/models \
  -H "Authorization: Bearer sk-u-xxx" | jq .

返回当前用户可访问的模型列表。如果返回 401，检查 API Key 是否正确、用户是否启用；如果返回 403，检查用户模型白名单。

模型名说明：列表中的模型名是 ModelItem 的 display_name（控制台模型管理中配置的名称），不是上游 model_name。调用时使用 display_name。

第 3 步：发起对话

非流式请求：

curl -s https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}]}'

这里的 gpt-4o 是你在控制台配置的 display_name，请替换为实际值。

流式请求（SSE）：

curl -N https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"stream":true}'

流式响应要点：

• 平台每 15 秒发送心跳 : PING，客户端应跳过所有 : 开头的行。

• 正常结束标记：data: [DONE]。

• 流式错误格式：

  event: error
  data: {"error":{"message":"...","type":"upstream_error"}}
  

• 流式错误事件之后不会再发送 [DONE]，客户端必须处理 event: error。

第 4 步：指定 Agent

通过 agent_id 参数使用平台 Agent 的配置（系统提示词、绑定模型、技能等）：

curl -s https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"agent_id":"e3k8Z2..."}'

agent_id 必须是加密字符串（EncryptedID），不接受明文整数 ID。加密字符串可在控制台 Agent 详情页或接口返回中获取。

带 agent_id 时模型鉴权规则变化：不再看用户白名单，而是按 Agent 绑定模型鉴权。Agent 未绑定模型时回退租户默认模型 / 默认模型组。详见 添加与配置模型。

第 5 步：使用模型组

模型组支持多模型路由。调用时在 model 字段使用 group- 前缀 + 模型组名称：

curl -s https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"group-my-group","messages":[{"role":"user","content":"你好"}]}'

控制台 / 数据库中模型组的 name 不含 group- 前缀；调用 API 时必须加 group- 前缀。详见 模型组：多模型路由。

第 6 步：工具调用（function calling）

在请求中传 tools 和 tool_choice，支持 OpenAI 标准 function calling：

curl -s https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "查询北京天气"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

工具类型说明：

mcp__ 前缀的工具是平台服务端工具，由 Pipeline 自动调用租户注册的 MCP Server。不带 mcp__ 前缀的是客户端工具，需要调用方自己执行后把结果回传给模型。

第 7 步：配置 SDK

OpenAI Python：

from openai import OpenAI

client = OpenAI(
    base_url="https://www.aimatespace.com/openai/v1",
    api_key="sk-u-xxx",
)

# 普通对话
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)

# 指定 Agent（通过 extra_body 传平台扩展参数）
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={"agent_id": "e3k8Z2..."},
)

OpenAI Node：

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://www.aimatespace.com/openai/v1',
    apiKey: 'sk-u-xxx',
});

LangChain：

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://www.aimatespace.com/openai/v1",
    api_key="sk-u-xxx",
    model="gpt-4o",
)

LlamaIndex：

from llama_index.llms.openai import OpenAI

llm = OpenAI(
    api_base="https://www.aimatespace.com/openai/v1",
    api_key="sk-u-xxx",
    model="gpt-4o",
)

私有部署时，把 base_url / baseURL / api_base 替换为 http://<host>:8002/openai/v1。

第二部分：MCP Gateway 接入

第 1 步：确认接入地址

MCP Gateway 使用与 OpenAI 兼容 API 相同的用户 API Key（sk-u- 开头）认证。确保该用户所属租户已注册 MCP Server 并同步了工具，详见 注册上游 MCP Server。

第 2 步：initialize 握手

所有 MCP 客户端首先需要发送 initialize 请求完成协议握手：

curl -s https://www.aimatespace.com/mcp \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "curl", "version": "1.0.0"}
    }
  }'

返回服务端能力信息，确认握手成功。

第 3 步：tools/list 发现工具

握手成功后，列出当前租户所有可用 MCP 工具：

curl -s https://www.aimatespace.com/mcp \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

返回工具列表，每个工具名格式为 {server_name}__{tool_name}，例如 weather__get_forecast。

工具命名空间：MCP 客户端拿到的工具名是 {server_name}__{tool_name}（双下划线）。其中 server_name 是注册 MCP Server 时填写的标识，tool_name 是上游 Server 提供的原始工具名。

第 4 步：tools/call 调用工具

调用具体工具：

curl -s https://www.aimatespace.com/mcp \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "weather__get_forecast",
      "arguments": {"city": "北京"}
    }
  }'

工具名必须使用完整的 {server_name}__{tool_name} 格式。调用日志可在控制台 排查调用日志 中查看。

第 5 步：配置 MCP 标准客户端

Cursor / Claude Desktop / 通用 MCP 客户端配置：

{
  "mcpServers": {
    "platform-gateway": {
      "type": "streamable-http",
      "url": "https://www.aimatespace.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-u-xxx"
      }
    }
  }
}

私有部署时，把 url 替换为 http://<host>:8003/mcp。

配置后，MCP 客户端会自动完成 initialize -> tools/list 流程，发现租户注册的所有 MCP 工具，供 LLM 调用。

怎么验证成功了

OpenAI 兼容 API

1. GET /openai/v1/models 能返回模型列表（非空）
2. 非流式 POST /openai/v1/chat/completions 能返回内容
3. 流式请求能正确处理 : PING 心跳、event: error 错误和 [DONE] 结束标记
4. 指定 Agent 时 agent_id 是加密字符串且能正常响应
5. 模型组调用使用 group- 前缀名称且能正常响应
6. 控制台 查 Token 统计 中能看到调用记录

MCP Gateway

1. initialize 握手成功，返回服务端能力信息
2. tools/list 返回工具列表（数量大于 0）
3. tools/call 能成功调用工具并返回结果
4. 控制台 排查调用日志 中能看到调用记录
5. MCP 标准客户端配置后能自动发现工具

常见问题

调用返回 401 认证失败

请检查：

1. 使用的是完整的用户 API Key（sk-u- 开头），不是管理员登录密码
2. API Key 没有被删除或禁用
3. 用户账号没有被禁用
4. 请求地址正确：OpenAI 兼容接口 https://www.aimatespace.com/openai/v1，MCP Gateway https://www.aimatespace.com/mcp

调用返回 403 权限不足

• 模型无权访问：检查用户模型白名单是否包含该模型。白名单为空时直接返回 403，平台管理员和租户 admin 也不豁免。
• 客户端不在白名单：如果租户启用了客户端白名单（allowed_api_clients），确认调用方客户端在白名单中。
• Agent 未分配：指定 agent_id 时，确认该 Agent 已分配给当前用户。

调用返回 503 服务不可用

Agent 路径下返回 503，通常是 Agent 未绑定模型且租户未配置默认模型 / 默认模型组。请检查：

1. Agent 是否绑定了模型
2. 租户是否设置了默认模型或默认模型组（至少配置其一）

base_url 末尾带了 / 导致请求失败

部分 SDK 在 base_url 以 / 结尾时会拼成 //chat/completions，导致 404。去掉末尾的 /。

流式响应解析出错

1. 没有跳过 : PING 心跳行（以 : 开头的行应忽略）
2. 流式错误后等待 [DONE]（错误事件后不会再发 [DONE]，必须处理 event: error）
3. SDK 与 cURL 表现不一致时，先打印实际 URL、请求头和请求体排查

MCP tools/list 返回空

1. 确认租户已注册 MCP Server 且 is_enabled=true
2. 确认 Server 健康状态 server_status=active
3. 在控制台手动点击「刷新工具」重新同步
4. 查看 排查调用日志 确认是否有错误

MCP tools/call 提示工具不存在

工具名必须使用完整的 {server_name}__{tool_name} 格式（双下划线）。确认 server_name 是注册时填写的标识，tool_name 是 tools/list 返回的原始工具名。

agent_id 报错「无效」

agent_id 必须是加密字符串（EncryptedID），不接受明文整数 ID。从控制台 Agent 详情页或接口返回中获取加密字符串。同时确认该 Agent 已分配给当前用户。

深入

核心概念

OpenAI 兼容 API 端点

所有端点均使用用户 API Key 认证。

Chat 请求参数

模型鉴权规则

平台管理员和租户 admin 不豁免模型鉴权。带 agent_id 时用户白名单不参与判断。

工具命名空间

配额和限制

错误码速查

错误响应格式（param 和 code 仅在存在时返回）：

{"error":{"message":"...","type":"..."}}

平台业务错误：

上游 LiteLLM 映射：

常见坑

1. base_url 末尾别带 /：避免 SDK 拼成 //chat/completions。
2. 流式响应要跳过 : PING：以 : 开头的行是心跳，不是数据。
3. 流式错误后无 [DONE]：客户端必须处理 event: error。
4. mcp__ 前缀是服务端工具：平台 Pipeline 自动执行，无需客户端参与。
5. 不带 mcp__ 前缀是客户端工具：需要客户端自己执行后回传结果。
6. agent_id 必须是加密字符串：不接受明文整数 ID。
7. 模型鉴权不豁免管理员：Agent 路径看 Agent 绑定 / 租户默认；非 Agent 路径看用户白名单，白名单为空直接 403。
8. allow_external_role=False 时 system 消息被剥离：租户关闭外部角色后，客户端传的 system 消息会被入口剥离。
9. MCP 客户端工具名必须用 {server_name}__{tool_name}：双下划线，不是单下划线。
10. SDK 与 cURL 不一致时先抓包：打印实际 URL、请求头和请求体定位差异。

接入检查清单

上线前建议依次验证：

1. GET /openai/v1/models 能返回模型。
2. 非流式 POST /openai/v1/chat/completions 能返回内容。
3. 流式请求能正确处理 : PING、event: error 和 [DONE]。
4. 指定 Agent 时 agent_id 是加密字符串。
5. 模型组调用使用正确的 group- 名称。
6. MCP Gateway 能完成 initialize -> tools/list -> tools/call。
7. 控制台调用日志、安全事件和 MCP 调用日志可用于排查。

• 想了解如何创建 API Key？见 管理用户 API Key
• 想了解如何注册 MCP Server？见 注册上游 MCP Server
• 想了解模型鉴权完整规则？见 添加与配置模型
• 想了解 MCP 调用日志排查？见 排查调用日志