中枢运行中 · live Nexus v T0 单 ECS · 弹性可横扩
AI CAPABILITY HUB · NEXUS

一个 AI 能力中枢
汇聚 · 治理 · 分发

企业级 AI 中台 —— 汇聚 家厂商 · 分发 种原子能力, 为 款产品提供 统一鉴权 · 配额管控 · 调用审计 · 智能路由。 让每一次 AI 调用都可观测、可控制、可优化。

已激活能力源
/
分发 种原子能力
今日调用
最近 1h
今日成本
¥
P95 延迟 ms
调用健康度
%
今日错误 次 · 自愈中
AGGREGATE
汇聚 · 多源能力收口

对接阿里 DashScope / 字节火山 Ark / 硅基流动 / DeepSeek / OpenAI / Kimi / 智谱 等 21 家厂商,统一为 chat / translate / tts / asr / embed / vl / avatar 7 种原子能力。一个 endpoint,多家供应。

21 vendor 7 capability OpenAI-compat
GOVERN
治理 · 全链路可控

X-App-Key 鉴权 · 按 app/user 维度的 RPM 限流 + 日 CNY 配额 · 全量 调用审计 · 失败自动 熔断与降级。密钥零下放到端侧。

Auth · Quota Audit Circuit Breaker
DISTRIBUTE
分发 · 智能多路复用

SSE 9 事件 + JSON + job-poll 三协议自适应弱网移动端 · vendor/model 路由 可灰度可 A/B · Idempotency-Key 防重 · 对端侧零侵入升级。

SSE · JSON · Poll Routing · A/B Idempotent
GLOBAL EDGE NETWORK · 全球边缘网络

4 区 10 站 · 中枢节点全球分布

就近接入 · 智能调度 · 单区不可用自动 fail-over,全球 P95 < 60ms。
10/10 节点在线 跨区心跳 OK
实时同步 · 10 PoPs · 42 region routes
P95 · 42ms QPS · 3.4K UPTIME · 99.97%
SHA · 上海 PRIMARY · 12ms BJS · 北京 EDGE · 18ms HKG · 香港 EDGE · 22ms NRT · 东京 EDGE · 28ms SIN · 新加坡 EDGE · 34ms BOM · 孟买 EDGE · 48ms FRA · 法兰克福 EDGE · 38ms IAD · 弗吉尼亚 EDGE · 42ms SFO · 旧金山 EDGE · 51ms GRU · 圣保罗 EDGE · 56ms
PRIMARY · 主控 EDGE · 边缘节点 数据通道 · 实时同步
最近同步 ·
CN · 大中华区
3 节点
SHA · BJS · HKG
平均 RT 17 ms
APAC · 亚太
3 节点
NRT · SIN · BOM
平均 RT 37 ms
EMEA · 欧洲中东
1 节点
FRA · 法兰克福
平均 RT 38 ms
AMERICAS · 美洲
3 节点
IAD · SFO · GRU
平均 RT 49 ms
COST INTELLIGENCE · 经济价值

每一次 AI 调用的真实成本

所有数字来自 /system/overview 实时聚合 —— 内存 ring 缓冲(最近 次调用)。
实时聚合
RING 累计成本 · 最近 次调用
LIVE
¥
来自内存 ring buffer(cap ),ring 时间跨度 不是"全时累计" —— ring 满后老事件被覆盖。持久化全时统计走 audit_log (PG),T1 上线。
tokens in tokens out errors · %
TODAY vs LAST HOUR · 实时窗口对比
LIVE
TODAY · 24H
¥
次调用
p95 ms
LAST HOUR · 1H
¥
次调用
p95 ms
TOP VENDOR BY COST · /system/stats LIVE
QUOTA GUARD · 配额护栏
LIVE
熔断在位
日 CNY 配额 + RPM 双层熔断(plugins/quota.ts)。
SMART ROUTING · 比价路由
ROADMAP
规划中
同质能力按 cost-per-token 自动选最优 vendor。当前 vendor 由调用方显式指定(strict-vendor)。
SEMANTIC CACHE · 语义缓存
ROADMAP
规划中
embedding 相似度命中跳过 vendor。当前仅 Idempotency-Key exact-match 防重(plugins/idempotency.ts)。
AUTO DOWNGRADE · 智能降级
ROADMAP
规划中
高峰自动 Max → Turbo 切换。当前只有 /translate 多 vendor 串行 fallback。
REQUEST ORCHESTRATION · 请求编排

每次调用的真实链路

flow 严格反映当前 src/routes/ai/*.ts 实现 —— LIVE 已上线 / ROADMAP 规划中,绝不挂羊头卖狗肉。
实时反映代码
REQUEST JOURNEY · 当前实现的真实 4 段链路
LIVE ROADMAP
1AUTHLIVE
入口鉴权
X-App-Key · scope 校验 · Idempotency-Key 防重放 · 每应用配额检查
plugins/auth.ts · idempotency.ts · quota.ts
2RESOLVELIVE
Vendor 解析
caller-specified vendor 走 adapter registry;缺 key 直接 503,不静默 fallback
adapters/base.ts registry
3EXECUTELIVE
Vendor 调用 + 重试
SSE/JSON/job-poll 三协议;指数退避重试 5xx/429/timeout(withRetry)
adapters/base.ts withRetry()
4AUDITLIVE
回写 · 计费 · ring 落盘
tokens / cost_cny / latency / status 全字段进 ring( /
plugins/stats.ts onResponse
LIVE
Retry with Backoff
5xx / 429 / network timeout 指数退避自动重试。non-retryable 错误(auth / invalid model)直接抛。
exp-backoffisRetryable()
PARTIAL
Vendor Fail-over
/translate 走多 vendor 串行链。/chat 故意 strict-vendor,避免 model 契约错乱。
translate-only
ROADMAP
Smart Routing
同 prompt 按 cost / latency / quality 策略选 vendor。当前未实现,vendor 由调用方显式指定。
costlatencyquality
ROADMAP
Semantic Cache
embedding 相似度命中跳过 vendor。当前仅 Idempotency-Key exact-match 防重,不是语义缓存。
embeddingcosine ≥ 0.92
SECURITY & COMPLIANCE · 安全与合规

现在的真实防线 + 规划中的扩展

LIVE 来自 /system/overview.protections;认证均为 PLANNED 状态 —— 不挂未取得的徽章。
SOC
2
SOC 2 TYPE II
数据安全控制
PLANNED
未启动审计。计划 开始第三方滚动审计(访问控制 / 加密 / 变更管理 / 事件响应)。
ISO
27001
ISO/IEC 27001
信息安全管理
PLANNED
未启动认证流程。目标 完成内审 + 外审,覆盖 ISMS 全链路。
等保
三级
国家等保 三级
DSL · 网安法
PLANNED
未启动测评。目标 完成等保 2.0 三级,覆盖云资源 / 数据 / 应用。
GDPR
GDPR · 跨境合规
数据主体权利
PLANNED
未启动合规建设。目标 完成 DPA + 隐私政策 + 跨境数据落地区控制。
SECURITY JOURNEY · 真实闸门 + 规划闸门
前 4 步 LIVE(已在代码里)· 后 4 步 ROADMAP(未实现,不假装)。
LIVE ROADMAP
01
入口鉴权 + 作用域 LIVE X-App-Key
每应用一把 App Key,scope 校验细到 endpoint 级。plugins/auth.ts
02
幂等 · 防重放 LIVE Idempotency-Key
同 key + 同 body → 直接返回缓存结果;同 key + 不同 body → 409 拒绝。plugins/idempotency.ts
03
配额熔断 LIVE quota
日 CNY 配额 + RPM 双层熔断 → 429。plugins/quota.ts
04
调用审计 ring LIVE in-memory · 10K events
当前 ring / 事件;窗口 非 30 天持久化 —— audit_log (PG) T1 上线。plugins/stats.ts
05
上行内容审核 ROADMAP moderation
违禁词 / 涉敏 / prompt injection 检测。**目前未实现** —— 业务自行兜底。
06
PII 自动脱敏 ROADMAP redaction
手机号 / 身份证 / 邮箱 / 银行卡在送达 vendor 前自动遮罩。**目前未实现**。
07
跨境合规路由 ROADMAP geo-routing
按请求地理自动选区域 vendor。**目前未实现** —— vendor 由调用方显式指定。
08
下行幻觉检测 ROADMAP hallucination-guard
vendor 输出二次审:低置信度标记 / 危险输出拦截。**目前未实现**。
CAPABILITY MATRIX · 原子能力矩阵

7 种 AI 原子能力 · 一套 SSE / JSON 协议

每种能力都做了多 vendor 适配 + 协议统一,端侧只关心业务,不关心谁在算。
CONSUMERS · 中枢接入产品矩阵

款产品共享同一中枢

教育 · 翻译 · 助手 · 工业 — 跨形态、跨技术栈,共用一套 AI 能力供给。
数据源: apps/<id>.md
Experience Center

产品体验

中枢驱动的 款产品 — 教育 · 翻译 · 助手 · 工业。每一款都跑在同一套 AI 能力供给上。直接试用 H5,或查看桌面客户端的产品资料。

总产品数
已接入中枢
Web 体验
H5 / Web 直达
桌面客户端
Qt / Native
新近上线
近 30 天
Source
数据来自 apps/<id>.md manifest · 品牌色板自 brand_gradient · 体验入口自 deployed_url
auto refresh · s
REAL-TIME OBSERVABILITY

中枢实时面板

中枢全链路可观测:调用频次、Token 消耗、端到端延迟、错误分布按时间窗口聚合;Top apps · vendors · routes · models 实时排行。

调用量
总请求数
消耗 · CNY
¥
vendor 原价透传
Token in / out
/
prompt / completion
avg / P95 · ms
/
端到端延迟
调用频次 / 错误
bucket s
TOP · APPS
App调用错误CNY
无数据
TOP · VENDORS
Vendor调用错误CNY
无数据
TOP · ROUTES
Route调用avg ms错误
无数据
TOP · MODELS
Model调用tokensCNY
无数据
RECENT · 50 CALLS
时间 app route vendor model in/out ms CNY status
还没有调用记录 — 跑一发请求试试
analytics · live
INTELLIGENT ANALYTICS

智能分析

中枢深度分析层:跨产品调用概览 + 单产品下钻。覆盖流式健康、断流根因、per-vendor 性能画像、错误码分布 —— 让每一次异常都有迹可循。

Gate 0 · 全景占位
RESOURCE HUB · 资源中枢

资源 介入 · 治理 · 分发

把 AI 中枢升级为 AI + 知识 + 连接器 三位一体的能力底座。围绕 教育 / 会议 / 办公 / 出口贸易 / 细分行业 链接和补齐所需资源 —— 知识库、Prompt 模板、工具连接器、结构化数据、多媒体素材,统一目录、统一鉴权、统一计费。

snapshot 管家工作中 活动同步
正在加载资源全景…
AGENT BUTLER · 管家动作时间线
qwen-max 自治 · 日报 03:00 · 周日审计 04:00 · 失败按需诊断
同步于
LATEST REPORT · 管家最近一次产出

            
rounds= · tool_calls= · tokens=
管家待命中 · 下一次自动巡检 03:00
PENDING REVIEW · 待你拍板
· approve 即生效;reject 留痕
管家暂无待办 ✓
一切正常
SOURCE MANAGER · 源管理
· 手动触发立即抓取
加载源列表中…
DICTIONARY · 词典查询
未加载词典
输入词条并按回车查询
KNOWLEDGE TREE · 知识树
· · 基于 LLM 自动归类的课标树
还没标签数据 — 先按"⚡ AI 标签 200 条"跑一轮
加载中…
行业:
RESOURCE INVENTORY · 服务端分页 加载中… / 共
类型 名称 行业 归属 状态 标签 来源
当前筛选条件下无资源 · 试试切换 kind / 行业 / 关键词
RESOURCE HUB ROADMAP
Gate 1 · 静态目录 + 外部源
vendor 适配器 + apps 画像 + 11 个公开数据源
Gate 2 · 服务端分页(现状)
npm + PyPI + Iconify 全图标 + 机场全集;/summary + /list ajax 分页
Gate 3 · RAG 知识库
pgvector 召回 → chat 注入;教育错题库 + 出口贸易术语库先跑通
Gate 4 · Prompt / Tool 市场
版本化模板 + MCP server 注册中心 + A/B
Gate 5 · 行业包 + 计费
教育包 / 会议包 / 出口贸易包;资源调用单独 line item
EXTERNAL · 对外接入
4 个标准发现入口 · X-App-Key 鉴权 · catalog:read / mcp:invoke scope
v2026-06-12
CATALOG · 列出 tool 资源
curl https://ainextcore.cn/api/v1/catalog/list?kind=tool&limit=5 \
  -H "X-App-Key: pk_<your_slug>_<24c>"
MCP · 调用 catalog_search 工具
curl -X POST https://ainextcore.cn/api/v1/mcp \
  -H "X-App-Key: pk_<your_slug>_<24c>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
DATASET · 中国行政区抽样
curl -X POST https://ainextcore.cn/api/v1/catalog/datasets/china_provinces/sample \
  -H "X-App-Key: pk_<your_slug>_<24c>" \
  -d '{"n":5}'
PROMPT · 渲染模板
curl "https://ainextcore.cn/api/v1/catalog/prompts/<id>/render?vars=%7B%22subject%22%3A%22math%22%7D" \
  -H "X-App-Key: pk_<your_slug>_<24c>"
资源类 动词 endpoint 说明
toolPOST /api/v1/mcp (tools/call)JSON-RPC 2.0 · 4 内置 first-party 工具
promptGET /api/v1/catalog/prompts/:id/renderMustache-lite 变量替换 + 缺失声明
knowledgePOST /api/v1/catalog/knowledge/search语义 top-K 召回 (BGE/embed)
datasetPOST /api/v1/catalog/datasets/:id/sampleN 随机样本 · bundle 或单条
assetGET /api/v1/catalog/assets/:id/signed-urlHMAC 签名 · 外部资产返回 upstream
contentPOST /api/v1/catalog/content/search关键词 + subkind/owner 过滤
GOVERNANCE LAYER · 中枢治理

治理 · 策略中心

Vendor 总开关(全局 / 全 app)· service_policies 限流与配额策略 · 熔断降级规则。一切策略均可热生效,修改需 Admin Token。

需要 DATABASE_URL 才能编辑策略;当前 DISABLE_PG=1 模式下只能查看 vendor 列表。
VENDOR · GLOBAL TOGGLE
禁用后该 vendor 对所有 app 全局拒绝(POLICY_VENDOR_DISABLED)
vendor capabilities key 总开关
无 vendor
RATE-LIMIT POLICIES
数据源: · 共
scope enabled RPM 日额 (CNY) note 操作
vendor matrix
CAPABILITY SOURCES · 能力源

能力源 矩阵

中枢上游:21 家厂商 × 7 种能力 的对接矩阵。绿点 = key 已配置可调度,灰点 = 等待 key。下方按 vendor 展开已注册模型 catalog + 单价 + ctx。

Vendor key RPM
REGISTERED MODELS · CATALOG
classroom · live V4.3.1
CLASSROOM ANALYSIS · 区/校本评课中枢

AI 课堂实录与分析 · 评课 / 评分 / 目标达成

专家库做定制诊断 · 量表升级让评分有依据 · 教学目标看是否真正达成。完全 platform-api 内置,复用 Nexus 网关的 LLM / ASR 通道。

01

专家库

区/校本评课逻辑沉淀虚拟专家:关联课例后定制诊断 + 连续追问 + 改进建议。

定制诊断 关联课例 连续追问
02

量表升级

DOC/PDF 一键导入 → AI 自动拆解观测点与评价细则 → 一键 AI 优化补全分层标准。

一键导入 自动解析 AI 补全
03

教学目标

从目标出发回看结构 / 行为 / 策略 / 成效四维,判断预设目标是否达成。

目标为起点 学情差异 达成度回看

最近课例

全部 →

API 端点速查

  • GET/api/v1/classroom/stats
  • GET/api/v1/classroom/experts
  • POST/api/v1/classroom/rubrics/import
  • POST/api/v1/classroom/rubrics/import/file
  • POST/api/v1/classroom/lessons
  • POST/api/v1/classroom/lessons/:id/transcript/audio
  • POST/api/v1/classroom/lessons/:id/analyze
  • POST/api/v1/classroom/experts/:id/diagnose
鉴权:W0 demo 全 auth-skip · X-App-Key 兼容(principal.appId → 自动隔离)
存储:W0 in-memory + JSON 快照 (var/classroom-store.json) · W2 切 004 PG migration
docs · onboarding v
INTEGRATION HUB · 接入中心

把中枢资源 接到你的 App

5 步从零到第一次 AI 调用 · 4 种接入方式按场景选 · 5 类资源全部可用 · 8 个生产级 reference 实现可抄作业。所有 endpoint 都在

FIVE-STEP ONBOARDING · 5 步上手

从零到第一次 AI 调用

每一步都映射到中枢真实 endpoint / admin tab,点击即跳。
01AUTH
申请 App Key
联系运维(或自跑 seed 脚本)拿 pk_<app>_<24-char>。绑定 scope + 配额。
/admin#apps →
02CAPABILITY
选 7 种能力
chat / translate / tts / asr / embed / vl / avatar。一个 app 可同时用多个。
能力矩阵 →
03VENDOR
选 vendor + model
21 厂商 × 7 能力的真实矩阵。 家已激活。
/admin#vendors →
04CALL
写 5 行代码
cURL / Python / TS / Qt 任选。下方有 4 种接入方式对比 + 现成 snippet。
查看示例 ↓
05OBSERVE
接监控 + 分析
实时面板看调用 / 智能分析看健康度 / silent-for 告警自动触发。
/admin#stats →
INTEGRATION PATTERNS · 4 种接入方式

按 app 形态选最合适的接入方式

每张卡上的「使用产品」都是当前 8 个 reference 实现的真实归属,不是假想。
A
LIVE
Direct HTTP
backend → /api/v1/ai/*

最直接。你的后端服务直接 POST 中枢 endpoint。X-App-Key 在服务端 env,永远不下放端侧。

复杂度 · 极低 安全 · 高 语言无关
# fetch / curl / OkHttp / 任何 HTTP client
POST /api/v1/ai/chat
X-App-Key: pk_xxx
{"messages":[...]}
B
LIVE RECOMMENDED
BFF Proxy
H5 / Mobile → your BFF → 中枢

推荐给 H5 / 移动端。你的 BFF 服务做透传 + 用户态注入,端侧只跟自己 BFF 通信,App Key 永不下放。

复杂度 · 中 安全 · 最高 弱网友好
// Node BFF (Express / Hono / Fastify)
app.post('/api/chat', async (req, res) => {
  // 注入 X-App-Key(服务端 env)
  const r = await fetch(GW + '/ai/chat', {
    headers: { 'X-App-Key': process.env.KEY },
    body: req.body,
  });
});
使用产品:
C
LIVE
Native Adapter
Qt · Electron · Tauri · Flutter

桌面 / 跨端原生 App 用。一个 Adapter 类封装 X-App-Key 管理 + SSE 解析 + 事件分发,给业务层用 Qt signal / Promise / Future。

复杂度 · 高 安全 · 高 SSE 原生
// Qt5 / C++ — 已有 PlatformGatewayClient
PlatformGatewayClient gw("http://...", KEY);
connect(&gw, &Client::textChunk,
        this, &Self::onChunk);
gw.streamChat(req);
使用产品:
D
PARTIAL
Official SDK
pip install / npm i / go get

官方 SDK 封装鉴权 / SSE 解析 / 重试 / 错误码。Python 已发包,其余语言 ROADMAP。

Python LIVE Node ROADMAP Go ROADMAP
# pip install -e sdk/python
from platform_api_sdk import PlatformClient
cli = PlatformClient(base=BASE, app_key=KEY)
for ev in cli.stream_chat(messages=...):
    if ev.type == "text": print(ev.delta)
使用产品:
RESOURCE CATALOG · 你能从中枢拿到什么

10 类资源 · 每类对应一个真实 endpoint

所有数字都来自 /system/overview.assets 实时聚合。下方 4 张资产卡是 2026-05-26 架构师审计后新增的中间层资产。
LIVE 10/10
IDENTITY · 身份与权限
App Key + Scope

一个 app 一把 key(pk_<app>_<24-char>),绑定可访问 scope + RPM + 日 CNY 配额。

/admin#apps scripts/seed-app-key.ts
CATALOG · 厂商与模型
Vendor + Model 目录

家厂商 × 能力的真实矩阵,含单价 / 上下文窗口 / 输出上限。

/admin#vendors GET /system/vendors
ENDPOINTS · 原子能力
7 个 AI Endpoint

chat · translate · tts · asr · embed · vl · avatar,统一 SSE / JSON 协议,OpenAI 兼容。

/docs ↗ /api/v1/ai/*
SDK · 多语言客户端
SDK + OpenAPI Spec

Python SDK 已发包,其余语言可拉 OpenAPI 用 openapi-generator 自动生成。

openapi.json ↗ sdk/python/
OBSERVABILITY · 可观测
Stats + Analytics

实时调用 / per-app 用量 / 流式健康 / 断流告警 / Hourly chart。接入即可见。

/admin#stats /system/stats
GOVERNANCE · 治理策略
Quota + Audit + Errors

配额护栏 · 13 错误码 · ring 审计 · X-RateLimit-* 响应头自适应限流。

/admin#services plugins/quota.ts
PROMPTS · 共享 Prompt 库
Prompt Registry
LIVE

个版本化 prompt(YAML),跨 app 复用。每个含变量定义 + 推荐 tier / model。

GET /system/prompts prompts/*.yaml
KB · 托管向量库
Managed Knowledge Base
LIVE

条向量, 个 namespace · dim 。RAG / 语义检索 / 重复去重。

TIER · 能力别名
Capability Alias
LIVE

tier: 'fast' | 'quality' | 'cheap' 代替硬编码 vendor + model。 个 capability 已落 tier 映射。

body.tier plugins/tier.ts
FEEDBACK · 质量信号
Feedback + Eval
LIVE

质量回路( / 反馈, 正 · 负)+ vendor 评测 baseline。

POST /feedback · GET /eval routes/feedback.ts
ARCHITECT AUDIT · 2026-05-26 落码追踪

从「网关」升级到「资产中枢」

资深架构师审计识别 P0 / P1 / P2 共 8 项,现已落码 5 项 LIVE。Egress 厂商对接外,新增 4 层中间层资产(prompts / KB / tier / feedback+eval)。
P0 1/2
关键 vendor 配 key
anthropic / openai / iflytek 3 vendor 仍缺 key(agentboard 等 3 个 app 依赖)。需用户私有密钥。
manual config
P0 LIVE
managed KB · RAG 基础
embed + 向量检索作为 RAG 基础设施落码。mandarea / subject-grader / sensor-ai 可接入。
plugins/kb.ts /kb/upsert
P1 LIVE
tier 能力别名
app 写 tier: 'fast' 代替硬编 vendor+model。已接入 /ai/chat。
plugins/tier.ts
P1 LIVE
Prompt Registry
5 个 prompt 已抽出(mandarea/subject-grader/agentboard/sensor-ai/echo)。版本化 YAML,跨 app 复用。
prompts/*.yaml
P1 LIVE
Avatar 4→1 降级
aliyun_wan_s2v 主用 LIVE,其余 3 vendor 改为 roadmap_on_demand。释放维护成本 4×。
overview.avatar_vendors
P2 LIVE
Feedback 通道
POST /feedback 捕获质量信号(+1/0/-1 + corrected_output)。T1 → PG feedback_log。
routes/feedback.ts
P2 LIVE
Eval 框架
GET /system/eval 提供 2 个 baseline(chat-quality / translate-zh-id)。T1 实跑。
routes/eval.ts
P2 ROADMAP
audit_log PG 持久化
ring 升级为 PG audit_log,留 30 天可查询审计 + 月度账单。
T1 · pgvector
P3 ROADMAP
网关独立 ECS
单 ECS T0 部署 → 网关独立 + CDN + 多 region failover。
T2
P3 ROADMAP
语义缓存
基于 KB 层提取语义命中。同 prompt 不同表达走同一份缓存结果。
on KB foundation
REFERENCE IMPLEMENTATIONS · 抄作业

8 个生产级 reference 实现

integration_mode 分组 —— 找形态最像的,去看代码。
APPENDIX · 完整契约 + Code Snippets + FAQ
1
领取 App Key
Dev 期:用固定 pk_dev_local_only 直接连本机 gateway。
生产期:联系平台管理员(或自跑 seed 脚本)申请 pk_<app_id>_<24-char>
# 在 platform-api 仓库 root 下
DATABASE_URL=postgres://… npx tsx scripts/seed-app-key.ts mandarea-prod 100 1200
# 输出 raw_app_key 一次性可见,自己拷走存好
2
调用示例
/ai/chat (SSE 流式)
curl -N \
  -H "X-App-Key: pk_mandarea_prod_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "vendor": "siliconflow",
    "model": "Qwen/Qwen2.5-72B-Instruct",
    "messages": [{"role":"user","content":"你好"}],
    "stream": true
  }' \
  /api/v1/ai/chat
/ai/translate
curl -H "X-App-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","source_lang":"en","target_lang":"zh"}' \
  /api/v1/ai/translate
/ai/tts (返回 audio 字节流)
curl -H "X-App-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "vendor":"siliconflow",
    "model":"FunAudioLLM/CosyVoice2-0.5B",
    "voice":"FunAudioLLM/CosyVoice2-0.5B:alex",
    "text":"hello world","format":"mp3"
  }' \
  /api/v1/ai/tts --output out.mp3
/ai/asr (multipart 上传)
curl -H "X-App-Key: $KEY" \
  -F "file=@audio.mp3" \
  -F "vendor=siliconflow" \
  -F "language=zh" \
  /api/v1/ai/asr
/ai/embed
curl -H "X-App-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"input":["sentence one","sentence two"]}' \
  /api/v1/ai/embed
非流式 chat (fetch)
const r = await fetch(`${BASE}/api/v1/ai/chat`, {
  method: 'POST',
  headers: {
    'X-App-Key': APP_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    vendor: 'dashscope',
    model: 'qwen-turbo',
    messages: [{ role: 'user', content: 'Hi' }],
    stream: false,
  }),
});
const json = await r.json();
console.log(json.data.message.content);
流式 chat (ReadableStream)
const r = await fetch(`${BASE}/api/v1/ai/chat`, {
  method: 'POST',
  headers: { 'X-App-Key': APP_KEY, 'Content-Type': 'application/json', Accept: 'text/event-stream' },
  body: JSON.stringify({ vendor: 'siliconflow', model: 'Qwen/Qwen2.5-7B-Instruct',
    messages: [{ role: 'user', content: '写一首短诗' }], stream: true }),
});
const reader = r.body!.getReader();
const dec = new TextDecoder();
let buf = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  let idx;
  while ((idx = buf.indexOf('\n\n')) !== -1) {
    const frame = buf.slice(0, idx); buf = buf.slice(idx + 2);
    const ev = frame.match(/^event: (\w+)/m)?.[1];
    const dataLine = frame.match(/^data: (.+)$/m)?.[1];
    if (!dataLine) continue;
    const data = JSON.parse(dataLine);
    if (ev === 'text') process.stdout.write(data.text);
  }
}
httpx 非流式
import httpx

resp = httpx.post(
    f"{BASE}/api/v1/ai/chat",
    headers={"X-App-Key": APP_KEY},
    json={
        "vendor": "siliconflow",
        "model": "Qwen/Qwen2.5-7B-Instruct",
        "messages": [{"role": "user", "content": "Hi"}],
        "stream": False,
    },
    timeout=60,
)
print(resp.json()["data"]["message"]["content"])
流式 SSE
import json, httpx

with httpx.stream(
    "POST",
    f"{BASE}/api/v1/ai/chat",
    headers={"X-App-Key": APP_KEY, "Accept": "text/event-stream"},
    json={"vendor": "dashscope", "model": "qwen-turbo",
          "messages": [{"role": "user", "content": "写一首诗"}],
          "stream": True},
    timeout=90,
) as r:
    event = None
    for line in r.iter_lines():
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data = json.loads(line[5:].strip())
            if event == "text": print(data["text"], end="", flush=True)
Python SDK(已发包)
# pip install -e D:/Claude/platform-api/sdk/python
from platform_api_sdk import PlatformClient

cli = PlatformClient(base=BASE, app_key=APP_KEY)
for ev in cli.stream_chat(
    vendor="siliconflow",
    model="deepseek-ai/DeepSeek-V3",
    messages=[{"role": "user", "content": "解释一下 TP 菲林"}],
):
    if ev.type == "text": print(ev.delta, end="", flush=True)
Qt5 / C++ — 已有现成 PlatformGatewayClient(参考 blackboard 项目)
// blackboard/src/ai/providers/PlatformGatewayClient.{h,cpp} — 复用
PlatformGatewayClient gw("", "pk_app_xxxxx");

QJsonObject req;
req["vendor"] = "dashscope";
req["model"] = "qwen-turbo";
req["stream"] = true;
req["messages"] = QJsonArray{ QJsonObject{
    {"role", "user"}, {"content", "Hi"}
}};

connect(&gw, &PlatformGatewayClient::textChunk, this, [](const QString& t){
    qDebug() << t;
});
connect(&gw, &PlatformGatewayClient::done, this, [](){ qDebug() << "stream done"; });
gw.streamChat(req);
3
SSE 事件契约(9 种)
tool_call 多帧到达,调用方必须按 id 串接 arguments_delta 才能拼出完整 JSON arguments。详见 docs/sse-protocol.md §3.3
4
错误码速查
codeHTTPretry说明
API CONTRACT REFERENCE

接入规范

必须读完再上线。规范覆盖鉴权、限流、幂等、流式、版本、计费、超时、可观测、最佳实践共 9 项。

§A · 鉴权(Authentication)
必填:X-App-Key

每次请求带上 X-App-Key: pk_<app>_<24-char>。错误 / 缺失 → 401 AUTH_INVALID_KEY。Key 隔离应用维度,绑定 RPM 上限 / 日额度 CNY / 可访问 scope

可选:Authorization: Bearer <JWT>

如果你的 app 已有用户登录态,可签 HS256 JWT 传过来,payload 必须含 subapp_id(与 X-App-Key 匹配,否则 401)。本平台不发 JWT — 你的 app 自己签自己验。

Key 永不放客户端代码 / localStorage。Web/H5 必须经你的后端转发;移动端可短期持有但需服务端轮换接口。泄漏立刻找平台 revoke。
§B · 限流与配额(Rate Limits)

三层叠加:App RPM × User RPM × 日 CNY 配额。超额一律 429。

层级默认超额返回重置时间
App RPM1200 / 分钟(per app_id)429 QUOTA_RATE_LIMITED下一分钟边界
User RPM60 / 分钟(如带 JWT)429 QUOTA_RATE_LIMITED下一分钟边界
日 CNY 配额100 CNY / 天(per app_id)429 QUOTA_DAILY_EXCEEDEDUTC 0 点
每次响应都附带:
X-RateLimit-Limit-App: 1200
X-RateLimit-Remaining-App: 1197
X-RateLimit-Reset: 1716700860   # epoch 秒,下一桶重置时刻
X-Quota-Daily-Limit-CNY: 100
X-Quota-Daily-Remaining-CNY: 87.32
Retry-After: 27               # 只在 429 时出现,秒数
收到 429 → 读 Retry-After 退避,不要瞬时重试;建议 jittered exponential backoff,base 1s,cap 60s。
§C · 幂等(Idempotency)

非流式 POST(translate / tts / asr / embed)支持 Idempotency-Key 请求头。同 key + 同 body 24h 内重发 → 直接重放上次响应,不会重复计费

POST /api/v1/ai/translate
X-App-Key: pk_xxx
Idempotency-Key: txn_abc123_2026_05_25_v1   # 8-256 字符,建议 sha256(body) 或业务 ID
Content-Type: application/json

{...}

# 首次:返回正常 + 响应头 Idempotency-Stored: true
# 重放:返回缓存 + 响应头 Idempotency-Replayed: true
# 同 key 但 body 改了:409 IDEMPOTENCY_KEY_REUSED
SSE 流式 chat 不可幂等(流不可重放)。如果想要可重放,用 POST /ai/chat/job + GET /ai/chat/job/:id 模式。
§D · 流式(Server-Sent Events)
订阅触发条件
  • body stream: true(默认)
  • Accept: text/event-stream
  • 响应 Content-Type: text/event-stream; charset=utf-8
超时 & 心跳
  • 15s 无数据 → 服务端发 event: ping 心跳
  • 90s 无 ping 也无数据 → 视为断流,客户端应重连
  • 客户端关连接 → 自动取消上游 vendor 请求(节费)
每帧形如:event: text\ndata: {"text":"hi"}\n\ntool_call 多帧拼接,详见 §3。
§E · 版本与兼容性
  • URL 版本:所有路径都在 /api/v1/*。大破坏性变更 → 平行启 /api/v2/*,旧版至少保留 6 个月。
  • 响应头X-API-Version: 0.1.0 每次返回,可用于客户端兼容性日志。
  • 新增字段非破坏:response/event 加新 key 不触发版本变更。客户端必须忽略未知字段,不要 strict-mode 解析。
  • 枚举值兼容:vendor / model id 列表会扩,已有 id 永不撤销。新 vendor 上线只追加,不打破现有调用。
  • 弃用通知:endpoint/字段废弃前 30 天,响应头 Deprecation: true + Sunset: <RFC1123 date> 公告。
§F · 计费透明(Cost)

网关原价透传 vendor 报价,不加价;每次成功响应回填实际成本。

# /ai/chat 非流式响应
{
  "ok": true,
  "data": {/* ... */},
  "usage": { "prompt_tokens": 18, "completion_tokens": 42, "total_tokens": 60 },
  "request_id": "req_..."
}

# /ai/tts 响应头
X-Vendor: siliconflow
X-Model: FunAudioLLM/CosyVoice2-0.5B
X-Usage-Characters: 11
X-Usage-Cost-Cny: 0.000022
实时面板见 Stats;按 app 维度聚合见 Apps
§G · 最佳实践
  • 长生成用流式,让用户看到首字延迟;短调用用 stream:false 拿完整 JSON 更省事。
  • embed 用批处理:一次塞 ≤64 条字符串到 input 数组,比逐条调便宜 + 快。
  • 明确 vendor + model:不显式选会用 vendor 默认模型;多 vendor 比较时务必 pin。同 vendor 不同 model 走严格校验,不会 silent fallback。
  • tool_call 多帧重组:按 id 串接 arguments_delta 才能拼出完整 JSON(§3.3 有 TS 范例)。
  • 幂等关键操作:批改、写库、扣费类调用必传 Idempotency-Key,重试不重扣。
  • 读限流头自适应:客户端封装 SDK 时,封装一个全局 rate-limiter 读 X-RateLimit-* 自我节流,比被动 429 重试体感更好。
  • 错误分类处理retryable: true 的错(429/502/504)才重试;retryable: false 立刻报告用户。
  • 移动端弱网:用 job-poll 不用 SSE,POST /ai/chat/jobjob_idGET /ai/chat/job/:id?since=N 轮询。
  • 不要轮询健康:用 /healthz 间隔 ≥ 30s;高频探活会污染 stats ring。
  • OpenAPI 拉取/openapi.json 给 SDK codegen 用。
§H · 全 endpoint 参数总表
endpoint method 必填 可选 流式 幂等 默认 vendor
§I · FAQ
billing · 账单中心 加载中…
COST CENTER · TOKEN 费用

账单 中心

看哪个 App 花了多少、花在哪里、相比上期涨跌几何。日级 rollup 已持久化,周 / 月 / 季度切片随时切换;点应用卡进 drilldown 看模型与能力级账单。

¥
vs 上一可比期 ¥
月末预测
Token · 总量 / 单价
tok
in · out ¥ / 1K tok · 单次均价 ¥
每日成本 ·
generated
VENDOR · 账户余额(实时)
总余额 ¥ · 家可查 / 家在册

按 App ·

点卡片进 drilldown · 抽屉里看模型 / 能力 / 供应商级账单

按本期花费排序
每日热力 · 近 90 天
单元格颜色越深 = 当日费用越高 · hover 查看详情
最近 8 周
每周成本 · 周一 → 周日
全局明细 ·
调用 Token 成本 ¥ ¥/1K tok 占比
环比涨跌 · TOP MOVERS
本期 vs 上一可比期,按绝对金额变化排序
数据源:每日 var/cost-daily/YYYY-MM-DD.json rollup(cost-rollup plugin,每 60s 从 stats ring snapshot 持久化)+ 当日 live 直读 ring。app × model 准确归因。 T1 接入 PG audit_log 后接口形状不变,存储层无感切换。
cost · breaker
DAILY COST CAP · 成本熔断

成本 熔断

按 appKey × UTC 日窗的 CNY 累计。达到 cap 立即 429 COST_CAP_EXCEEDED,到 UTC 0 点自动重置。优先级:app_keys.cost_cap_daily_cny > env CAP_DEFAULT_DAILY_CNY。

audit · immutable
TAMPER-EVIDENT AUDIT LOG

审计 链路

每条 AI/Domain 请求一行:hash_self = sha256(prev_hash + canonical_json(row))。任意一行被改动,chain 校验会在该行立即报错。

sla · cascade
VENDOR SLA · FALLBACK CASCADE

SLA 降级

每能力一条链:5xx / 网络错 / 429 跳下一家;4xx 直抛。5 分钟窗口内某厂商失败 ≥ 5 次自动开断路器,TTL 到期自愈。