zclaw_openfang/docs/setup/chinese-models.md

# 中文模型配置指南

> 本文档详细介绍 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 月*