docs: add setup guides and error notification component
- Add OpenFang Kernel configuration guide (docs/setup/OPENFANG-SETUP.md) - Add Chinese models configuration guide (docs/setup/chinese-models.md) - Add quick start guide (docs/quick-start.md) - Add quick start scripts for Windows and Linux/macOS - Add ErrorNotification component for centralized error display These additions help users: - Quickly set up development environment - Configure OpenFang backend correctly - Configure Chinese LLM providers (GLM, Qwen, Kimi, MiniMax) - See error notifications in a consistent UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
472
docs/setup/chinese-models.md
Normal file
472
docs/setup/chinese-models.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# 中文模型配置指南
|
||||
|
||||
> 本文档详细介绍 OpenFang Kernel 支持的中文大语言模型，以及如何获取和配置 API Key。
|
||||
|
||||
---
|
||||
|
||||
## 支持的中文模型
|
||||
|
||||
OpenFang 通过 OpenAI 兼容 API 支持所有主流中文模型提供商：
|
||||
|
||||
| 提供商 | 模型系列 | 特点 | 定价 |
|
||||
|--------|----------|------|------|
|
||||
| **智谱 AI** | GLM-4 | 国产领先，多模态支持 | 免费 + 付费 |
|
||||
| **阿里云** | 通义千问 (Qwen) | 性价比高，企业级 | 按量计费 |
|
||||
| **月之暗面** | Kimi | 长上下文（200K） | 按量计费 |
|
||||
| **MiniMax** | 海螺 AI | 语音能力强 | 按量计费 |
|
||||
| **百度** | 文心一言 | 企业应用广泛 | 按量计费 |
|
||||
| **DeepSeek** | DeepSeek | 编程能力强，低价 | 极低价格 |
|
||||
| **百川智能** | Baichuan | 中文优化 | 按量计费 |
|
||||
| **上海 AI Lab** | 书生浦语 | 开源模型 | 免费 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 智谱 GLM
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `glm-4-flash` | 128K | 快速响应，免费额度 | 日常对话、快速问答 |
|
||||
| `glm-4` | 128K | 旗舰模型 | 复杂任务、推理 |
|
||||
| `glm-4-plus` | 128K | 增强版 | 专业应用 |
|
||||
| `glm-4-air` | 128K | 轻量版 | 简单任务 |
|
||||
| `glm-4v` | 8K | 多模态（图像理解） | 图像分析 |
|
||||
| `glm-4-long` | 1M | 超长上下文 | 长文档处理 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [智谱开放平台](https://open.bigmodel.cn/)
|
||||
2. 注册/登录账号
|
||||
3. 进入「API Keys」页面
|
||||
4. 点击「创建 API Key」
|
||||
|
||||
**免费额度**：新用户赠送 1000 万 tokens
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.zhipu]
|
||||
provider = "zhipu"
|
||||
model = "glm-4-flash"
|
||||
api_key_env = "ZHIPU_API_KEY"
|
||||
base_url = "https://open.bigmodel.cn/api/paas/v4"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export ZHIPU_API_KEY="your-zhipu-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 通义千问 (Qwen)
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `qwen-turbo` | 8K | 快速版 | 快速问答 |
|
||||
| `qwen-plus` | 32K | 增强版 | 复杂任务 |
|
||||
| `qwen-max` | 32K | 旗舰版 | 高质量输出 |
|
||||
| `qwen-max-longcontext` | 200K | 长上下文 | 长文档 |
|
||||
| `qwen-vl-plus` | 8K | 多模态 | 图像理解 |
|
||||
| `qwen-vl-max` | 8K | 多模态增强 | 高精度图像 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [阿里云百炼](https://dashscope.console.aliyun.com/)
|
||||
2. 登录阿里云账号
|
||||
3. 开通「灵积模型服务」
|
||||
4. 获取 API Key
|
||||
|
||||
**免费额度**：部分模型有免费试用
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.qwen]
|
||||
provider = "openai-compat"
|
||||
model = "qwen-turbo"
|
||||
api_key_env = "DASHSCOPE_API_KEY"
|
||||
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export DASHSCOPE_API_KEY="your-dashscope-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Kimi (Moonshot)
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `moonshot-v1-8k` | 8K | 基础版 | 日常对话 |
|
||||
| `moonshot-v1-32k` | 32K | 长上下文 | 中等文档 |
|
||||
| `moonshot-v1-128k` | 128K | 超长上下文 | 长文档分析 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [Moonshot AI 开放平台](https://platform.moonshot.cn/)
|
||||
2. 注册/登录账号
|
||||
3. 进入「API Key 管理」
|
||||
4. 创建新的 API Key
|
||||
|
||||
**免费额度**：新用户赠送 15 元体验金
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.kimi]
|
||||
provider = "openai-compat"
|
||||
model = "moonshot-v1-8k"
|
||||
api_key_env = "MOONSHOT_API_KEY"
|
||||
base_url = "https://api.moonshot.cn/v1"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export MOONSHOT_API_KEY="your-moonshot-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. MiniMax
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `abab6.5-chat` | 8K | 旗舰对话 | 通用对话 |
|
||||
| `abab6.5s-chat` | 8K | 快速版 | 快速响应 |
|
||||
| `abab6.5g-chat` | 8K | 通用版 | 平衡场景 |
|
||||
| `abab5.5-chat` | 16K | 经典版 | 日常使用 |
|
||||
| `abab5.5s-chat` | 16K | 轻量版 | 简单任务 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [MiniMax 开放平台](https://www.minimaxi.com/)
|
||||
2. 注册/登录账号
|
||||
3. 进入「账户管理」->「API Key」
|
||||
4. 创建 API Key
|
||||
|
||||
**注意**：MiniMax 需要同时配置 Group ID
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.minimax]
|
||||
provider = "openai-compat"
|
||||
model = "abab6.5-chat"
|
||||
api_key_env = "MINIMAX_API_KEY"
|
||||
base_url = "https://api.minimax.chat/v1"
|
||||
|
||||
[model.minimax.headers]
|
||||
# MiniMax 需要 Group ID
|
||||
"x-minimax-group-id" = "your-group-id"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export MINIMAX_API_KEY="your-minimax-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. DeepSeek
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `deepseek-chat` | 64K | 通用对话 | 日常使用 |
|
||||
| `deepseek-coder` | 16K | 代码专精 | 编程任务 |
|
||||
| `deepseek-reasoner` | 64K | 深度推理 | 复杂推理 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [DeepSeek 开放平台](https://platform.deepseek.com/)
|
||||
2. 注册/登录账号
|
||||
3. 进入「API Keys」页面
|
||||
4. 创建 API Key
|
||||
|
||||
**定价优势**：极低价格，性价比高
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.deepseek]
|
||||
provider = "openai-compat"
|
||||
model = "deepseek-chat"
|
||||
api_key_env = "DEEPSEEK_API_KEY"
|
||||
base_url = "https://api.deepseek.com"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export DEEPSEEK_API_KEY="your-deepseek-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 百度文心一言
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `ernie-4.0-8k` | 8K | 旗舰版 | 复杂任务 |
|
||||
| `ernie-3.5-8k` | 8K | 标准版 | 日常使用 |
|
||||
| `ernie-speed-8k` | 8K | 快速版 | 快速响应 |
|
||||
| `ernie-lite-8k` | 8K | 轻量版 | 简单任务 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [百度智能云千帆平台](https://console.bce.baidu.com/qianfan/)
|
||||
2. 登录百度账号
|
||||
3. 创建应用，获取 API Key 和 Secret Key
|
||||
|
||||
**注意**：文心一言使用 access_token 认证，需要额外处理
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.wenxin]
|
||||
provider = "openai-compat"
|
||||
model = "ernie-4.0-8k"
|
||||
api_key_env = "WENXIN_ACCESS_TOKEN"
|
||||
base_url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 百川智能
|
||||
|
||||
### 模型列表
|
||||
|
||||
| 模型 | 上下文 | 特点 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| `Baichuan4` | 128K | 旗舰版 | 复杂任务 |
|
||||
| `Baichuan3-Turbo` | 32K | 快速版 | 日常使用 |
|
||||
| `Baichuan3-Turbo-128k` | 128K | 长上下文 | 长文档 |
|
||||
|
||||
### API Key 获取
|
||||
|
||||
1. 访问 [百川智能开放平台](https://platform.baichuan-ai.com/)
|
||||
2. 注册/登录账号
|
||||
3. 获取 API Key
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.baichuan]
|
||||
provider = "openai-compat"
|
||||
model = "Baichuan4"
|
||||
api_key_env = "BAICHUAN_API_KEY"
|
||||
base_url = "https://api.baichuan-ai.com/v1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 本地模型 (Ollama)
|
||||
|
||||
如果你想在本地运行开源中文模型：
|
||||
|
||||
### 支持的开源模型
|
||||
|
||||
| 模型 | 参数量 | 内存需求 | 特点 |
|
||||
|------|--------|----------|------|
|
||||
| `qwen2:7b` | 7B | 8GB | 通用对话 |
|
||||
| `qwen2:14b` | 14B | 16GB | 高质量输出 |
|
||||
| `glm4:9b` | 9B | 12GB | 智谱开源版 |
|
||||
| `deepseek-coder:6.7b` | 6.7B | 8GB | 代码专精 |
|
||||
|
||||
### 安装 Ollama
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
|
||||
# Windows
|
||||
# 访问 https://ollama.com/download 下载安装包
|
||||
```
|
||||
|
||||
### 下载模型
|
||||
|
||||
```bash
|
||||
# 下载通义千问
|
||||
ollama pull qwen2:7b
|
||||
|
||||
# 下载 GLM4
|
||||
ollama pull glm4:9b
|
||||
```
|
||||
|
||||
### 配置示例
|
||||
|
||||
```toml
|
||||
[model.ollama]
|
||||
provider = "openai-compat"
|
||||
model = "qwen2:7b"
|
||||
base_url = "http://localhost:11434/v1"
|
||||
# 本地模型无需 API Key
|
||||
api_key_env = ""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 多模型配置
|
||||
|
||||
OpenFang 支持同时配置多个模型，并自动路由：
|
||||
|
||||
```toml
|
||||
# ~/.openfang/config.toml
|
||||
|
||||
[model]
|
||||
# 默认模型
|
||||
provider = "zhipu"
|
||||
model = "glm-4-flash"
|
||||
|
||||
# 备选模型
|
||||
[[model.alternates]]
|
||||
name = "coding"
|
||||
provider = "deepseek"
|
||||
model = "deepseek-coder"
|
||||
api_key_env = "DEEPSEEK_API_KEY"
|
||||
|
||||
[[model.alternates]]
|
||||
name = "long-context"
|
||||
provider = "kimi"
|
||||
model = "moonshot-v1-128k"
|
||||
api_key_env = "MOONSHOT_API_KEY"
|
||||
|
||||
[[model.alternates]]
|
||||
name = "local"
|
||||
provider = "openai-compat"
|
||||
model = "qwen2:7b"
|
||||
base_url = "http://localhost:11434/v1"
|
||||
|
||||
# 模型路由规则
|
||||
[model.routing]
|
||||
# 编程任务使用 DeepSeek Coder
|
||||
coding = ["deepseek-coder", "glm-4"]
|
||||
# 长文档使用 Kimi
|
||||
long_context = ["moonshot-v1-128k", "glm-4-long"]
|
||||
# 快速响应使用 Flash 或本地模型
|
||||
fast = ["glm-4-flash", "qwen2:7b"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 价格对比
|
||||
|
||||
| 模型 | 输入价格 (元/百万 tokens) | 输出价格 (元/百万 tokens) |
|
||||
|------|---------------------------|---------------------------|
|
||||
| GLM-4-Flash | 免费 | 免费 |
|
||||
| GLM-4 | 100 | 100 |
|
||||
| 通义千问-Turbo | 2 | 6 |
|
||||
| 通义千问-Max | 40 | 120 |
|
||||
| Kimi-8K | 12 | 12 |
|
||||
| DeepSeek-Chat | 1 | 2 |
|
||||
| DeepSeek-Coder | 1 | 2 |
|
||||
|
||||
*价格仅供参考，以官方最新公告为准*
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 模型选择建议
|
||||
|
||||
| 场景 | 推荐模型 | 理由 |
|
||||
|------|----------|------|
|
||||
| 日常对话 | GLM-4-Flash | 免费且速度快 |
|
||||
| 编程任务 | DeepSeek-Coder | 专业代码能力 |
|
||||
| 长文档分析 | Kimi-128K | 超长上下文 |
|
||||
| 复杂推理 | GLM-4 / Qwen-Max | 高质量输出 |
|
||||
| 离线使用 | Ollama + Qwen2 | 本地运行 |
|
||||
|
||||
### 2. API Key 安全
|
||||
|
||||
- 永远不要在代码或配置文件中硬编码 API Key
|
||||
- 使用环境变量存储敏感信息
|
||||
- 定期轮换 API Key
|
||||
- 为不同项目使用不同的 API Key
|
||||
- 设置 API Key 使用额度限制
|
||||
|
||||
### 3. 成本控制
|
||||
|
||||
```toml
|
||||
[metering]
|
||||
# 每日最大花费（美元）
|
||||
daily_budget = 5.0
|
||||
# 每个 Agent 每小时最大 tokens
|
||||
hourly_token_limit = 100000
|
||||
# 超限行为：reject（拒绝）或 downgrade（降级）
|
||||
on_limit = "downgrade"
|
||||
# 降级到的模型
|
||||
fallback_model = "glm-4-flash"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何测试 API Key 是否有效？
|
||||
|
||||
```bash
|
||||
# 使用 curl 测试智谱 API
|
||||
curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \
|
||||
-H "Authorization: Bearer $ZHIPU_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model": "glm-4-flash", "messages": [{"role": "user", "content": "你好"}]}'
|
||||
```
|
||||
|
||||
### Q: 多个模型如何切换？
|
||||
|
||||
在 Agent 配置中指定：
|
||||
|
||||
```toml
|
||||
[agent.my-agent]
|
||||
[model]
|
||||
provider = "deepseek"
|
||||
model = "deepseek-coder"
|
||||
```
|
||||
|
||||
### Q: 如何查看用量？
|
||||
|
||||
```bash
|
||||
# 查看今日用量
|
||||
openfang usage --today
|
||||
|
||||
# 查看本月用量
|
||||
openfang usage --month
|
||||
|
||||
# 按模型分组
|
||||
openfang usage --group-by model
|
||||
```
|
||||
|
||||
### Q: API Key 泄露了怎么办？
|
||||
|
||||
1. 立即在对应平台撤销泄露的 Key
|
||||
2. 生成新的 API Key
|
||||
3. 更新环境变量
|
||||
4. 检查账单是否有异常使用
|
||||
|
||||
---
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [智谱开放平台](https://open.bigmodel.cn/)
|
||||
- [阿里云百炼](https://dashscope.console.aliyun.com/)
|
||||
- [Moonshot 平台](https://platform.moonshot.cn/)
|
||||
- [MiniMax 开放平台](https://www.minimaxi.com/)
|
||||
- [DeepSeek 平台](https://platform.deepseek.com/)
|
||||
- [Ollama 官网](https://ollama.com/)
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026 年 3 月*
|
||||
Reference in New Issue
Block a user