chenxin
42513d13c6
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# 模型网关兼容 API
|
||
|
||
## 1. 边界
|
||
|
||
兼容网关提供模型推理协议，不是 Hunjing 角色或 Agent Runtime 的替代入口：
|
||
|
||
```text
|
||
https://gateway.<deployment-domain>/openai/v1
|
||
https://gateway.<deployment-domain>/anthropic/v1
|
||
```
|
||
|
||
- 它可以接受工具定义并返回 tool call，但不会自动执行客户端工具。
|
||
- 它不读写 Character、Memory、Conversation、Community、DeviceGrant、Order 或 PluginInstallation。
|
||
- 需要 Hunjing 自动工具循环、多 Agent、审批和持久化时，调用 Native `/v1/runs`。
|
||
|
||
## 2. OpenAI-compatible 子集
|
||
|
||
1.0 支持：
|
||
|
||
```text
|
||
GET /openai/v1/models
|
||
POST /openai/v1/responses
|
||
POST /openai/v1/chat/completions
|
||
POST /openai/v1/embeddings
|
||
POST /openai/v1/images/generations
|
||
POST /openai/v1/audio/transcriptions
|
||
POST /openai/v1/audio/speech
|
||
```
|
||
|
||
认证：
|
||
|
||
```http
|
||
Authorization: Bearer hjk_...
|
||
```
|
||
|
||
流式响应遵循对应 OpenAI SSE 子集；响应返回 `x-request-id` 和 `Hunjing-Request-ID`。未支持的请求字段返回明确 `unsupported_parameter`，不静默忽略会改变语义的字段。
|
||
|
||
## 3. Anthropic Messages-compatible 子集
|
||
|
||
1.0 支持：
|
||
|
||
```text
|
||
GET /anthropic/v1/models
|
||
POST /anthropic/v1/messages
|
||
POST /anthropic/v1/messages/count_tokens
|
||
```
|
||
|
||
认证和版本：
|
||
|
||
```http
|
||
x-api-key: hjk_...
|
||
anthropic-version: <supported-version>
|
||
```
|
||
|
||
OAuth 客户端也可用 `Authorization: Bearer`。网关返回 `request-id` 和 `Hunjing-Request-ID`。`anthropic-beta` 只允许 Adapter 明确支持的值；未知 beta 返回 400，不透传到任意上游。
|
||
|
||
Messages Tool Use 保留 `tool_use.id` / `tool_result.tool_use_id` 关联；Thinking、cache、usage、stop reason 和 SSE block 必须按所声明兼容版本转换，无法无损映射时拒绝而非伪造。
|
||
|
||
## 4. 模型名与路由
|
||
|
||
请求 `model` 优先解析 Hunjing 逻辑模型，例如：
|
||
|
||
```text
|
||
default-chat
|
||
fast-chat
|
||
reasoning-chat
|
||
vision-chat
|
||
embedding-default
|
||
image-default
|
||
speech-default
|
||
```
|
||
|
||
管理员可允许部分上游模型别名，但业务客户端不应依赖 Provider 密钥或 Endpoint。模型配置按固定顺序继承：平台硬边界 → 平台目录 → 用户偏好/BYOK → 角色覆写 → 会话临时选择；上层约束不可被下层覆盖，会话临时选择不持久化，切换模型不得改变角色身份。能力槽（chat、vision、ASR、TTS、image generation、embedding、rerank、safety 等）由逻辑模型声明。`GET models` 只返回当前调用主体获准、在其地区可用的模型和能力。
|
||
|
||
路由依次考虑：scope、地区、隐私级别、能力、上下文、工具/结构化输出支持、预算、健康、配额和优先级。
|
||
|
||
## 5. Header 策略
|
||
|
||
客户端 Header 默认不转发。Adapter 逐 Provider 声明 allowlist，例如：协议版本、项目/组织选择和特性开关。以下字段永不直接转发：
|
||
|
||
- Hunjing 用户 `Authorization`/Cookie；
|
||
- `Hunjing-Diagnostic-Token`；
|
||
- 客户端提交的上游 API key；
|
||
- 未登记 Provider beta；
|
||
- `baggage` 中未批准的键；
|
||
- Hop-by-hop Header。
|
||
|
||
上游凭据由 Secret Store 按 Endpoint 注入。常规日志只记录允许的 Header 名和不可逆摘要，不记录值。
|
||
|
||
## 6. 重试、故障转移和流提交
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> routing
|
||
routing --> requesting
|
||
requesting --> retrying : retryable before visible output
|
||
retrying --> requesting
|
||
requesting --> streaming : first visible event
|
||
requesting --> completed : non-stream success
|
||
streaming --> completed
|
||
streaming --> failed : stream error
|
||
requesting --> failed
|
||
```
|
||
|
||
- 只在首个用户可见事件前对安全的错误重试/故障转移。
|
||
- 首个可见事件后禁止切换 Provider 重新生成；当前流继续或明确失败。
|
||
- 每个 attempt 单独创建 ModelCall；SDK 自身重试也必须可观测。
|
||
- 429 遵循 `Retry-After`；上下文错误、认证、权限和内容拒绝不做同请求盲重试。
|
||
|
||
## 7. Usage 标准化
|
||
|
||
标准字段见 `run-observability.md`。关键差异：
|
||
|
||
- Anthropic `usage.input_tokens` 表示未缓存输入，缓存创建/读取单列；
|
||
- OpenAI `usage.input_tokens` 通常含 cached tokens，Adapter 计算未缓存差值；
|
||
- Provider 未返回字段存 `null`，`usage_source=unavailable`；
|
||
- 平台估算必须标记 `gateway_estimate`，不能冒充 Provider usage；
|
||
- 成本由 Hunjing 价格版本计算，不信任上游返回成本；
|
||
- 流式 usage 可能只在末尾出现，流异常时允许部分 usage 或 unavailable。
|
||
|
||
## 8. BYOK 与 Service Account
|
||
|
||
- 兼容 API 只接受 Hunjing 凭据，不接受用户把 Provider Key 当认证凭据。
|
||
- BYOK 通过 Native Secret/Endpoint 配置写入，常规读取只返回掩码和状态。
|
||
- Service Account scope 可限制模型、能力、日/月预算、RPM/TPM、IP/来源和有效期。
|
||
- 同一个 API key 不跨 PersonalDomain/Workspace 自动访问。
|
||
|
||
## 9. 错误转换
|
||
|
||
兼容入口按目标协议返回错误 envelope，同时附：
|
||
|
||
```http
|
||
Hunjing-Request-ID: request_01...
|
||
traceparent: 00-...
|
||
```
|
||
|
||
内部保留标准错误和 Provider 原错误类别。不得把 Provider 私密正文、Endpoint、密钥状态或其他租户信息暴露给兼容客户端。
|