API Service（OpenAI / LangGraph 兼容）

API Service 把一个 Sira 应用暴露为符合行业标准的 HTTP API：

OpenAI Chat Completions 兼容 —— /v1/chat/completions，可直接被 OpenAI SDK / LangChain ChatOpenAI / 各种现成客户端使用
LangGraph Runs 兼容 —— /assistants/{id}/threads/{id}/runs/stream，可被 LangGraph SDK / LangSmith 工具链使用

两条接口都附带 API Key 管理、配额控制和限流，常用于将 Sira 作为内部 LLM 服务对外提供。

流式架构（直接 yield）

两条 API 端点都使用 execute_streaming_direct() —— 编排器产出的 chunk 通过 SSE 直接 yield 给客户端，不经过 Redis 中转，相比早期 Redis Stream 模式延迟约降低 50%。

平台同时保留了 Redis Stream 模式，仅供企业微信 AI Bot（受 5 秒回调超时约束）和遗留 WeChat 集成使用。两条路径在同一引擎里共存，按调用方自动选择，对用户无感。

License 提示

/v1/chat/completions 需要 channel.openai_compat (STANDARD)
/assistants/.../runs/stream 需要 channel.langgraph_compat (PROFESSIONAL)

详见 License 管理。

应用场景

对外提供 AI 服务：将 Sira AI 作为标准 LLM API 提供
统一API网关：整合多个 Agent，统一对外接口
多租户管理：通过 API Key 实现租户隔离和配额管理
成本控制：精细化的用量统计和限流

创建 API Service 应用

1. 进入应用管理

Agent System → 应用管理 → 创建应用

2. 填写基础信息

应用名称：api_service_llm（系统标识符）
显示名称：LLM API 服务（用户可见名称）
描述：功能说明

3. 选择平台类型

选择：API Service 🔌

4. 选择 Orchestrator

从下拉列表选择已创建的 Orchestrator。

5. 配置 API Service 参数

字段	说明	默认值
默认限流 (请求/分钟)	每个 API Key 的默认速率限制	100
默认配额限制	总配额上限	1000000
配额类型	tokens 或 requests	tokens

配额类型

Tokens：按 LLM Token 消耗计费，适用于 LLM 服务
Requests：按请求次数计费，适用于固定计费场景

6. 保存应用

点击创建，系统自动生成 API 端点。

API Key 管理

创建 API Key

在应用详情页，点击 API Keys 标签
点击 创建 API Key
填写信息：
- Key 名称：例如 "生产环境密钥"
- 描述：用途说明
- 速率限制：留空使用应用默认值
- 配额限制：留空无限制
- IP 白名单（可选）：限制访问IP
- 过期时间（可选）：留空永不过期
点击创建

重要

API Key 只在创建时显示一次，请立即复制并妥善保管！遗失后无法找回，只能重新创建。

API Key 格式

api_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

前缀：api_sk_
长度：32位随机字符
用途：Bearer Token 认证

管理 API Key

查看列表：

显示所有 API Key 的前缀和统计信息
查看使用情况、请求数、Token 消耗

更新配置：

修改速率限制和配额
更新 IP 白名单
修改描述信息

撤销 Key：

点击撤销按钮
Key 立即失效，无法恢复

重置配额：

将已使用配额重置为 0
适用于月度/年度配额重置场景

API 调用

API 端点

POST https://your-domain.com/v1/chat/completions

兼容 OpenAI Chat Completions API。

请求示例

bash

curl https://your-domain.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer api_sk_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "default",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ],
    "stream": true
  }'

请求参数

参数	类型	说明	必填
model	string	模型名称（固定为 "default"）	✅
messages	array	消息列表	✅
stream	boolean	是否流式响应	❌ (默认false)
temperature	number	温度参数	❌
max_tokens	number	最大Token数	❌

模型参数

由于 Sira AI 的模型在 Agent 层配置，API 层的 model 参数固定为 "default"，实际使用的模型由 Orchestrator 和 Agent 决定。

响应格式

流式（SSE）：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"default","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"default","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

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

data: [DONE]

非流式（JSON）：

json

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助您的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

LangGraph 兼容接口

License 提示

此接口需要 channel.langgraph_compat (PROFESSIONAL)。

把一个 Sira Application 暴露为 LangGraph Server——可被 LangGraph SDK、LangSmith、LangGraph Studio 直接消费。

端点

POST /assistants/{assistant_id}/threads/{thread_id}/runs/stream

assistant_id 对应 Sira Application ID，thread_id 对应 session id（用于多轮记忆）。

鉴权

与 OpenAI 兼容接口相同——使用 Authorization: Bearer api_sk_xxx。

请求示例（LangGraph SDK）

python

from langgraph_sdk import get_client

client = get_client(
    url="https://your-domain.com/api/agent-system",
    api_key="api_sk_xxx",
)

async for chunk in client.runs.stream(
    thread_id="session-001",
    assistant_id="<your-application-id>",
    input={"messages": [{"role": "user", "content": "你好"}]},
    stream_mode="messages",
):
    print(chunk)

与 OpenAI 兼容接口怎么选

选 OpenAI 接口	选 LangGraph 接口
客户端是 OpenAI SDK / 现成 LLM 工具	客户端是 LangGraph / LangSmith / LangChain 工作流
不需要中间事件（节点开始 / 工具调用等）	需要拿到编排器内部节点级事件
简单 chat 场景	调试 / 复杂工作流编排

输出语义

LangGraph 接口的 SSE 事件保留了完整的节点级别信息（哪个 Agent 在思考、何时调用了哪个工具、token 流如何到达），适合做调试或对接编排可视化工具。

OpenAI 接口则压平为标准的 delta.content chunk，丢弃节点信息，但兼容性最好。

配额和限流

速率限制（Rate Limiting）

限流层级：

API Key 级别：单个 Key 的每分钟请求数
应用级别：整个 Application 的总限制
系统级别：全局限制（可选）

限流响应：

json

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

HTTP 状态码：429 Too Many Requests

配额管理（Quota Management）

配额类型：

Tokens：按实际消耗的 LLM Tokens 计费
Requests：按请求次数计费

配额用尽响应：

json

{
  "error": {
    "message": "Quota exceeded",
    "type": "quota_error",
    "code": "quota_exceeded"
  }
}

HTTP 状态码：429 Too Many Requests

配额重置：

手动重置：在管理后台点击"重置配额"
自动重置：可通过定时任务实现月度/年度重置

客户端SDK

Python (OpenAI 官方SDK)

python

from openai import OpenAI

client = OpenAI(
    api_key="api_sk_xxxxxxxxxxxxxxxxxxxx",
    base_url="https://your-domain.com/v1"
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "你好"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript (OpenAI 官方SDK)

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'api_sk_xxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://your-domain.com/v1',
});

const stream = await client.chat.completions.create({
  model: 'default',
  messages: [{ role: 'user', content: '你好' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

安全最佳实践

API Key 安全

妥善保管：
- 不要在前端代码中硬编码
- 不要提交到版本控制系统
- 使用环境变量存储
定期轮换：
- 定期更换 API Key
- 旧 Key 撤销后立即更新
最小权限：
- 为不同场景创建独立的 Key
- 设置合理的配额和限流

访问控制

IP 白名单：
- 限制 API Key 的访问 IP
- 防止 Key 泄露后被滥用
HTTPS 强制：
- 强制使用 HTTPS
- 防止中间人攻击
监控告警：
- 监控异常请求
- 设置配额告警
- 及时发现安全问题

常见问题

API Key 创建后忘记复制

解决：

API Key 无法找回
需要撤销旧 Key 并创建新的

如何兼容 OpenAI SDK

说明：

Sira AI API Service 完全兼容 OpenAI Chat Completions API
只需修改 base_url 和 api_key 即可

如何实现多租户隔离

方案：

为每个租户创建独立的 API Key
设置不同的配额和限流
通过 API Key 统计各租户用量

配额类型如何选择

建议：

Tokens：适用于按 Token 计费的场景，成本与 LLM API 直接相关
Requests：适用于固定计费或不关心 Token 消耗的场景

下一步

Web 客户端 - Web 聊天界面
企业微信 AI Bot - 企业微信集成
多模态支持 - 图片处理
Orchestrator 配置 - 编排逻辑

API Service（OpenAI / LangGraph 兼容） ​

应用场景 ​

创建 API Service 应用 ​

1. 进入应用管理 ​

2. 填写基础信息 ​

3. 选择平台类型 ​

4. 选择 Orchestrator ​

5. 配置 API Service 参数 ​

6. 保存应用 ​

API Key 管理 ​

创建 API Key ​

API Key 格式 ​

管理 API Key ​

API 调用 ​

API 端点 ​

请求示例 ​

请求参数 ​

响应格式 ​

LangGraph 兼容接口 ​

端点 ​

鉴权 ​

请求示例（LangGraph SDK） ​

与 OpenAI 兼容接口怎么选 ​

输出语义 ​

配额和限流 ​

速率限制（Rate Limiting） ​

配额管理（Quota Management） ​

客户端SDK ​

Python (OpenAI 官方SDK) ​

JavaScript (OpenAI 官方SDK) ​

安全最佳实践 ​

API Key 安全 ​

访问控制 ​

常见问题 ​

API Key 创建后忘记复制 ​

如何兼容 OpenAI SDK ​

如何实现多租户隔离 ​

配额类型如何选择 ​

下一步 ​

API Service（OpenAI / LangGraph 兼容）

应用场景

创建 API Service 应用

1. 进入应用管理

2. 填写基础信息

3. 选择平台类型

4. 选择 Orchestrator

5. 配置 API Service 参数

6. 保存应用

API Key 管理

创建 API Key

API Key 格式

管理 API Key

API 调用

API 端点

请求示例

请求参数

响应格式

LangGraph 兼容接口

端点

鉴权

请求示例（LangGraph SDK）

与 OpenAI 兼容接口怎么选

输出语义

配额和限流

速率限制（Rate Limiting）

配额管理（Quota Management）

客户端SDK

Python (OpenAI 官方SDK)

JavaScript (OpenAI 官方SDK)

安全最佳实践

API Key 安全

访问控制

常见问题

API Key 创建后忘记复制

如何兼容 OpenAI SDK

如何实现多租户隔离

配额类型如何选择

下一步