Files
moyi-model-intelligence-hub/docs/07-provider-integration.md
T

56 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 首批模型供应商接入节点
本节点将模亦灵枢的首批供应商目录和适配器骨架落地,目标是先让内部测试可以使用一套统一的模型目录和 API,再逐家注入真实密钥进行联调。
## 接入矩阵
| 供应商 | 模亦灵枢接口 | 上游协议 | 首批模型 | 必要密钥 |
|---|---|---|---|---|
| DeepSeek | `POST /v1/chat/completions` | OpenAI 兼容 | `deepseek-v4-flash`、`deepseek-v4-pro` | `DEEPSEEK_API_KEY` |
| 月之暗面 Kimi | `POST /v1/chat/completions` | OpenAI 兼容 | `kimi-k3`、`kimi-k2.6` | `KIMI_API_KEY` |
| 智谱 GLM | `POST /v1/chat/completions` | OpenAI 兼容 | `glm-4.5`、`glm-4.5v` | `ZHIPU_API_KEY` |
| 字节 Seedance | `POST /v1/video/tasks` | 火山方舟异步任务 | `doubao-seedance-1-0-pro-250528` | `VOLCENGINE_API_KEY` |
DeepSeek 官方文档说明其 API 兼容 OpenAI 格式,默认地址为 `https://api.deepseek.com`:[DeepSeek API Docs](https://api-docs.deepseek.com/)。Kimi 官方文档说明 Kimi API 兼容 OpenAI 格式,平台地址和模型列表以官方文档为准:[Kimi API overview](https://www.kimi.ai/help/kimi-api/api-overview)、[Kimi models](https://platform.kimi.ai/docs/models)。Seedance 使用火山方舟的异步视频生成接口,创建任务后通过任务 ID 查询状态和 `video_url`:[Create video generation task](https://www.volcengine.com/docs/82379/2222480?lang=zh)、[Get video generation task](https://www.volcengine.com/api-docs/view?action=GetContentsGenerationsTask&serviceCode=ark&version=2024-01-01)。
智谱 GLM 的具体可用模型和区域以智谱开放平台账号内的官方模型列表为准;上线前不要把目录中的版本号视为永久不变,使用 `.env` 的 `ZHIPU_PRIMARY_MODEL` 和 `ZHIPU_VISION_MODEL` 覆盖即可。
## 服务端配置
复制 `control-plane/.env.example` 到本地 `.env`,只在服务端填写密钥:
```dotenv
DEEPSEEK_API_KEY=
KIMI_API_KEY=
ZHIPU_API_KEY=
VOLCENGINE_API_KEY=
```
可选地覆盖 Base URL 和上游模型标识:
```dotenv
DEEPSEEK_BASE_URL=https://api.deepseek.com
KIMI_BASE_URL=https://api.moonshot.cn/v1
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4
VOLCENGINE_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
```
真实密钥不得写入 Git、前端环境变量、模型目录或日志。当前没有配置密钥时,供应商仍会展示在模型目录,但调用会返回 `PROVIDER_NOT_CONFIGURED`,不会伪造真实上游响应。
## 验收顺序
1. 在管理端确认四家供应商和模型目录可见。
2. 创建一个 API Key,并在 Key 的“模型权限”中只选择一个待联调模型。
3. 用 `GET /v1/models` 确认该 Key 只看到已授权模型。
4. 用 `POST /v1/chat/completions` 验证 DeepSeek、Kimi、GLM 的非流式响应。
5. 用 `POST /v1/video/tasks` 验证 Seedance 创建任务,再用 `GET /v1/tasks/:id` 轮询。
6. 记录供应商响应时间、错误码、计量单位和失败扣费规则,为下一节点的流式转发、重试、路由和计费提供数据。
## 尚待提供的信息
- 每家供应商实际使用的 API Key,以及对应账号的区域和额度。
- GLM、Kimi 和 DeepSeek 最终验收的模型版本;如果与默认值不同,只需提供目标模型标识。
- Seedance 的火山方舟 Endpoint ID(如果不直接使用 Model ID)。
- 四家供应商是否允许在当前测试环境访问,以及并发、速率和内容安全限制。
- 首轮验收用的测试提示词、敏感内容边界和预期结果。