feat(docs): 更新文档，添加配置系统详解链接
This commit is contained in:
Wenjie Zhang
parent
7c699cc86f
commit
4b1a90a1d1
@ -1,212 +1,33 @@
|
||||
# 配置系统详解
|
||||
|
||||
Yuxi 采用了现代化的配置管理系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等特性。这套系统既满足了开发者对灵活配置的需求，又保证了运行时的稳定性。
|
||||
## 概述
|
||||
|
||||
## 设计理念
|
||||
系统采用多层配置架构，模型配置由网页界面管理，应用配置基于 Pydantic + TOML。
|
||||
|
||||
传统的配置文件往往存在以下问题：格式不统一、类型安全缺失、难以追踪哪些配置是用户修改过的。Yuxi 的配置系统针对这些问题给出了解决方案：
|
||||
|
||||
- **类型安全**：基于 Pydantic，所有配置项都有明确的类型定义
|
||||
- **智能提示**：IDE 可以根据类型定义提供自动补全
|
||||
- **选择性持久化**：只保存用户修改过的配置，避免版本冲突
|
||||
- **多层覆盖**：代码默认值 → TOML 文件 → 环境变量，按优先级覆盖
|
||||
|
||||
## 配置层次
|
||||
|
||||
系统采用三层配置结构，每一层都有不同的优先级和适用场景：
|
||||
## 配置层级
|
||||
|
||||
```
|
||||
配置优先级（从低到高）
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
环境变量 (.env) → 最高优先级，用于运行时覆盖
|
||||
用户配置 (TOML) → 持久化的用户修改
|
||||
代码默认值 → 最低优先级，定义在 Python 代码中
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
代码默认值 → TOML 文件 → 环境变量
|
||||
(低) (高)
|
||||
```
|
||||
|
||||
### 各层作用
|
||||
## 模型配置
|
||||
|
||||
1. **代码默认值**：定义在 `backend/package/yuxi/config/app.py` 和 `backend/package/yuxi/config/static/models.py` 中，提供所有配置项的初始值
|
||||
由网页统一管理，详见 [模型配置](./intro/model-config.md)。
|
||||
|
||||
2. **用户配置**：保存在 `saves/config/base.toml`，只包含用户实际修改过的配置项。这种设计的好处是：当代码更新添加了新配置项时，不会被用户的旧配置文件覆盖
|
||||
## 应用配置
|
||||
|
||||
3. **环境变量**：适用于容器化部署场景，可以方便地在启动时覆盖任意配置项
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 应用配置
|
||||
|
||||
主配置类 `Config` 继承自 Pydantic BaseModel：
|
||||
|
||||
```python
|
||||
class Config(BaseModel):
|
||||
# 功能开关
|
||||
enable_reranker: bool = Field(default=False, description="是否开启重排序")
|
||||
enable_content_guard: bool = Field(default=False, description="是否启用内容审查")
|
||||
|
||||
# 模型配置
|
||||
default_model: str = Field(default="siliconflow-cn:deepseek-ai/DeepSeek-V4-Flash")
|
||||
embed_model: str = Field(default="siliconflow-cn:BAAI/bge-m3")
|
||||
```
|
||||
|
||||
### 模型配置
|
||||
|
||||
模型配置独立管理，支持多种模型提供商:
|
||||
|
||||
```python
|
||||
DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
|
||||
"siliconflow": ChatModelProvider(
|
||||
name="SiliconFlow",
|
||||
url="https://cloud.siliconflow.cn/models",
|
||||
base_url="https://api.siliconflow.cn/v1",
|
||||
default="deepseek-ai/DeepSeek-V4-Flash",
|
||||
env="SILICONFLOW_API_KEY",
|
||||
models=["deepseek-ai/DeepSeek-V4-Flash", "Qwen/Qwen3-235B-A22B-Instruct-2507"],
|
||||
),
|
||||
# 其他提供商...
|
||||
}
|
||||
```
|
||||
|
||||
## 使用指南
|
||||
|
||||
### 读取配置
|
||||
|
||||
```python
|
||||
from yuxi.config import config
|
||||
|
||||
# 访问配置项
|
||||
model = config.default_model
|
||||
reranker_enabled = config.enable_reranker
|
||||
```
|
||||
配置项定义于 `backend/package/yuxi/config/app.py`，用户修改保存至 `saves/config/base.toml`。
|
||||
|
||||
### 修改配置
|
||||
|
||||
```python
|
||||
from yuxi.config import config
|
||||
|
||||
# 修改配置
|
||||
config.enable_reranker = True
|
||||
config.default_model = "custom-model-name"
|
||||
|
||||
# 保存到 TOML 文件
|
||||
config.save()
|
||||
```
|
||||
|
||||
### 配置验证
|
||||
|
||||
```python
|
||||
from yuxi.config import config
|
||||
|
||||
# 检查模型提供商可用性
|
||||
for provider, status in config.model_provider_status.items():
|
||||
print(f"{provider}: {'可用' if status else '不可用'}")
|
||||
|
||||
# 获取可用模型列表
|
||||
models = config.get_model_choices()
|
||||
embed_models = config.get_embed_model_choices()
|
||||
```
|
||||
|
||||
## 添加新模型提供商
|
||||
|
||||
需要支持新的模型提供商时，按以下步骤操作：
|
||||
|
||||
### 步骤 1：添加提供商配置
|
||||
|
||||
在 `backend/package/yuxi/config/static/models.py` 的 `DEFAULT_CHAT_MODEL_PROVIDERS` 字典中添加新条目：
|
||||
|
||||
```python
|
||||
"new-provider": ChatModelProvider(
|
||||
name="新提供商",
|
||||
url="https://provider.com/docs",
|
||||
base_url="https://api.provider.com/v1",
|
||||
default="default-model",
|
||||
env="NEW_PROVIDER_API_KEY",
|
||||
models=["model1", "model2"],
|
||||
),
|
||||
```
|
||||
|
||||
### 步骤 2：配置 API Key
|
||||
|
||||
在 `.env` 文件中添加对应的环境变量：
|
||||
|
||||
```env
|
||||
NEW_PROVIDER_API_KEY=your_api_key_here
|
||||
```
|
||||
|
||||
### 步骤 3：重启服务
|
||||
|
||||
配置完成后，重启服务使配置生效。
|
||||
|
||||
## 高级特性
|
||||
|
||||
### 动态更新
|
||||
|
||||
配置可以动态修改，无需重启服务：
|
||||
|
||||
```python
|
||||
from yuxi.config import config
|
||||
|
||||
# 更新单个配置项
|
||||
config.enable_reranker = True
|
||||
|
||||
# 更新模型列表
|
||||
config.model_names["siliconflow"].models.append("new-model")
|
||||
|
||||
# 保存修改
|
||||
config.save()
|
||||
```
|
||||
|
||||
### 导出配置
|
||||
|
||||
```python
|
||||
# 导出完整配置（包含运行时状态）
|
||||
full_config = config.dump_config()
|
||||
|
||||
# 导出用户配置（仅保存到文件的部分）
|
||||
user_config = {
|
||||
field: getattr(config, field)
|
||||
for field in config._user_modified_fields
|
||||
}
|
||||
```
|
||||
|
||||
### 选择性持久化机制
|
||||
|
||||
系统会跟踪哪些配置项被修改过：
|
||||
|
||||
```python
|
||||
# 假设用户只修改了 enable_reranker
|
||||
config.enable_reranker = True
|
||||
config.save() # 只保存 enable_reranker 到 TOML 文件
|
||||
```
|
||||
|
||||
生成的 TOML 文件只包含修改过的项：
|
||||
|
||||
```toml
|
||||
enable_reranker = true
|
||||
```
|
||||
|
||||
这种设计的优势：
|
||||
- 用户升级程序时，新配置项会自动使用默认值
|
||||
- 避免配置文件版本冲突
|
||||
- 便于查看用户做了哪些自定义修改
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q：新增的配置项没有生效？**
|
||||
|
||||
A：请检查：
|
||||
1. 配置项名称是否正确拼写
|
||||
2. 环境变量是否正确设置（环境变量优先级最高）
|
||||
3. 是否需要重启服务
|
||||
|
||||
**Q：如何查看当前所有配置？**
|
||||
|
||||
A：访问 `/api/config` 接口或查看 `config.dump_config()` 的输出。
|
||||
|
||||
**Q：配置文件格式错误导致启动失败？**
|
||||
|
||||
A：可以删除 `saves/config/base.toml` 文件，让系统重新生成默认配置。
|
||||
|
||||
---
|
||||
|
||||
配置系统的设计遵循了「约定优于配置」的原则，大多数情况下使用默认值即可工作。当需要自定义行为时，只需要修改少量配置项即可。理解这套系统的层次结构和优先级，能够帮助你更好地控制和调试应用行为。
|
||||
**配置文件损坏**：删除 `saves/config/base.toml`，系统将重新生成默认配置。
|
||||
|
||||
@ -1,243 +1,77 @@
|
||||
# 模型配置
|
||||
|
||||
## 对话模型
|
||||
## 概述
|
||||
|
||||
系统支持多种大语言模型服务商，通过配置对应的 API 密钥即可使用：
|
||||
系统统一通过 **系统设置 → 模型配置** 页面管理所有模型（对话模型、嵌入模型、重排模型），无需修改配置文件。
|
||||
|
||||
| 服务商 | 环境变量 | 特点 |
|
||||
| ------------------------------------------------ | ----------------------- | --------------------- |
|
||||
| [硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) | `SILICONFLOW_API_KEY` | 🆓 免费额度，默认推荐 |
|
||||
| OpenAI | `OPENAI_API_KEY` | GPT 系列模型 |
|
||||
| DeepSeek | `DEEPSEEK_API_KEY` | 国产大模型 |
|
||||
| [MiniMax](https://platform.minimaxi.com/) | `MINIMAX_API_KEY` | M2.7/M2.5 系列，百万 token 上下文 |
|
||||
| OpenRouter | `OPENROUTER_API_KEY` | 多模型聚合平台 |
|
||||
| 智谱清言 | `ZHIPUAI_API_KEY` | GLM 系列模型 |
|
||||
| 阿里云百炼 | `DASHSCOPE_API_KEY` | 通义千问系列 |
|
||||
## 配置路径
|
||||
|
||||
其余还支持火山豆包、Together、vLLM、Ollama 等。
|
||||
|
||||
### 配置方法
|
||||
|
||||
在 `.env` 文件中添加对应的环境变量：
|
||||
|
||||
::: tip 免费获取 API Key
|
||||
[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 16 元额度，支持多种开源模型。
|
||||
:::
|
||||
|
||||
<<< @/../.env.template#model_provider{bash 5}
|
||||
|
||||
## 自定义模型供应商
|
||||
|
||||
::: tip 自定义模型供应商仅支持对话模型
|
||||
自定义模型供应商仅支持对话模型，嵌入模型和重排模型请修改配置文件
|
||||
:::
|
||||
|
||||
系统提供了完整的自定义供应商管理功能，支持通过 Web 界面直接添加、编辑、测试和删除自定义模型供应商。
|
||||
|
||||
### 使用方法
|
||||
|
||||
系统支持任何 OpenAI 兼容的云服务提供商
|
||||
|
||||
#### 1. Web 界面操作（推荐）
|
||||
|
||||
访问 **系统设置 > 模型配置**，在"自定义供应商"部分点击 **添加自定义供应商**。这里的密钥可以直接填写也可以填写对应的环境变量名称。
|
||||
|
||||
#### 2. 配置文件操作
|
||||
|
||||
如需通过配置文件管理，编辑 `saves/config/custom_providers.toml`：
|
||||
|
||||
```toml
|
||||
[model_names.local-vllm]
|
||||
name = "本地 vLLM 服务"
|
||||
url = "https://docs.vllm.ai"
|
||||
base_url = "http://localhost:8000/v1"
|
||||
default = "Qwen/Qwen2.5-7B-Instruct"
|
||||
env = "LOCAL_VLLM_API_KEY"
|
||||
models = [
|
||||
"Qwen/Qwen2.5-7B-Instruct",
|
||||
"Qwen/Qwen2.5-14B-Instruct",
|
||||
]
|
||||
custom = true
|
||||
|
||||
[model_names.local-ollama]
|
||||
name = "本地 Ollama"
|
||||
url = "https://ollama.com"
|
||||
base_url = "http://localhost:11434/v1"
|
||||
default = "llama3.2"
|
||||
env = "NO_API_KEY"
|
||||
models = ["llama3.2", "qwen2.5"]
|
||||
custom = true
|
||||
```
|
||||
系统设置 → 模型配置
|
||||
```
|
||||
|
||||
然后在 `.env` 文件中添加对应的环境变量：
|
||||
## API 凭证配置
|
||||
|
||||
```env
|
||||
LOCAL_VLLM_API_KEY=your_api_key_here
|
||||
```
|
||||
支持两种凭证配置方式：
|
||||
|
||||
### API 端点
|
||||
| 方式 | 适用场景 |
|
||||
|------|----------|
|
||||
| 环境变量 | 生产环境或不愿在界面暴露 Key 的场景 |
|
||||
| 直接填写 | 开发调试，追求配置便利性 |
|
||||
|
||||
系统提供以下 API 端点管理自定义供应商：
|
||||
**环境变量方式**：在供应商配置中填写变量名（如 `SILICONFLOW_API_KEY`），确保运行时环境已配置对应变量。
|
||||
|
||||
- `GET /api/system/custom-providers` - 获取所有自定义供应商
|
||||
- `POST /api/system/custom-providers` - 添加自定义供应商
|
||||
- `PUT /api/system/custom-providers/{provider_id}` - 更新自定义供应商
|
||||
- `DELETE /api/system/custom-providers/{provider_id}` - 删除自定义供应商
|
||||
- `POST /api/system/custom-providers/{provider_id}/test` - 测试供应商连接
|
||||
**直接填写方式**：在供应商配置中直接填入 API Key。
|
||||
|
||||
### 常见配置示例
|
||||
## 供应商管理
|
||||
|
||||
#### vLLM 本地服务
|
||||
### 内置供应商
|
||||
|
||||
```toml
|
||||
[model_names.vllm-local]
|
||||
name = "vLLM 本地服务"
|
||||
base_url = "http://localhost:8000/v1"
|
||||
default = "Qwen/Qwen2.5-7B-Instruct"
|
||||
env = "NO_API_KEY"
|
||||
models = [
|
||||
"Qwen/Qwen2.5-7B-Instruct",
|
||||
"Qwen/Qwen2.5-14B-Instruct",
|
||||
"meta-llama/Llama-3.1-8B-Instruct"
|
||||
]
|
||||
```
|
||||
部分供应商默认启用，首次使用需配置 API 凭证：
|
||||
|
||||
#### Ollama 本地服务
|
||||
| 供应商 | Provider ID | 支持类型 | 备注 |
|
||||
|--------|-------------|----------|------|
|
||||
| SiliconFlow | `siliconflow-cn` | chat, embedding, rerank | 默认启用 |
|
||||
| OpenAI | `openai` | chat | |
|
||||
| DeepSeek | `deepseek` | chat | |
|
||||
| 阿里云百炼 | `alibaba` | chat | |
|
||||
| 智谱清言 | `zhipuai` | chat | |
|
||||
| MiniMax | `minimax-cn` | chat | |
|
||||
| OpenRouter | `openrouter` | chat, embedding | |
|
||||
|
||||
```toml
|
||||
[model_names.ollama-local]
|
||||
name = "Ollama 本地服务"
|
||||
base_url = "http://localhost:11434/v1"
|
||||
default = "llama3.2"
|
||||
env = "NO_API_KEY"
|
||||
models = [
|
||||
"llama3.2:latest",
|
||||
"qwen2.5:latest",
|
||||
"codellama:latest"
|
||||
]
|
||||
```
|
||||
### 操作流程
|
||||
|
||||
#### 第三方 API 中转服务
|
||||
1. **新增供应商**：点击「新增供应商」，填写基本信息（Provider ID、Base URL 等）
|
||||
2. **配置凭证**：填写 API Key 或环境变量名
|
||||
3. **启用供应商**：开启供应商状态开关
|
||||
4. **获取模型**：进入供应商详情，点击「获取远程模型」从 API 拉取可用模型列表
|
||||
|
||||
```toml
|
||||
[model_names.api-proxy]
|
||||
name = "API 中转服务"
|
||||
base_url = "https://api-proxy.example.com/v1"
|
||||
default = "gpt-5"
|
||||
env = "API_PROXY_KEY"
|
||||
models = [
|
||||
"gpt-5",
|
||||
"deepseek-chat",
|
||||
"claude-4.6-sonnet"
|
||||
]
|
||||
```
|
||||
## 模型管理
|
||||
|
||||
### 故障排除
|
||||
### 添加模型
|
||||
|
||||
1. **测试连接失败**: 检查 API 地址格式和 API 密钥配置
|
||||
2. **模型不可用**: 确认模型名称拼写和服务端是否支持该模型
|
||||
3. **权限错误**: 确保用户具有管理员权限
|
||||
4. **配置未生效**: 检查环境变量配置和服务重启状态
|
||||
**方式一：从远端拉取**
|
||||
|
||||
## 多模态模型
|
||||
进入供应商详情 → 点击「获取远程模型」→ 从候选列表中选择添加
|
||||
|
||||
系统支持图片作为输入，与文本结合形成多模态查询。
|
||||
**方式二：手动添加**
|
||||
|
||||
### 支持的图片格式
|
||||
进入供应商详情 → 点击「手动添加」→ 填写模型 ID 和类型
|
||||
|
||||
- JPEG、PNG、WebP、GIF、BMP
|
||||
- 最大 10MB
|
||||
- 超过 5MB 会自动压缩
|
||||
### 配置参数
|
||||
|
||||
### 使用方式
|
||||
嵌入模型（embedding）需配置向量维度，请参考模型提供商的规格说明。
|
||||
|
||||
在对话接口中传入图片数据：
|
||||
### 移除模型
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "这张图片里有什么？",
|
||||
"image_content": "<base64编码的图片数据>",
|
||||
"config": {},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
在供应商详情的已启用模型列表中移除不需要的模型。
|
||||
|
||||
系统会自动将图片转换为符合模型要求的格式，支持多模态的模型会同时处理图片和文本信息。
|
||||
## 旧版配置兼容性
|
||||
|
||||
### 支持多模态的模型
|
||||
本次更新前通过环境变量配置的模型（如 `SILICONFLOW_API_KEY`）依然有效，系统自动适配。旧配置不受影响，新增或修改模型时请使用新版界面。
|
||||
|
||||
大多数主流模型提供商都支持多模态能力，选择模型时需确认模型本身支持图片输入。
|
||||
## 常见问题
|
||||
|
||||
## 嵌入模型和重排序模型
|
||||
**凭证缺失警告**：检查 API Key 是否正确配置，或确认环境变量是否已设置。
|
||||
|
||||
#### 1. 配置模型信息
|
||||
|
||||
在 `backend/package/yuxi/config/static/models.py` 中的默认配置部分添加：
|
||||
|
||||
```python
|
||||
# 默认嵌入模型配置
|
||||
DEFAULT_EMBED_MODELS: dict[str, EmbedModelInfo] = {
|
||||
# ... 现有配置 ...
|
||||
|
||||
"vllm/Qwen/Qwen3-Embedding-0.6B": EmbedModelInfo(
|
||||
name="Qwen/Qwen3-Embedding-0.6B",
|
||||
dimension=1024,
|
||||
base_url="http://localhost:8000/v1/embeddings",
|
||||
api_key="no_api_key",
|
||||
),
|
||||
}
|
||||
|
||||
# 默认重排序模型配置
|
||||
DEFAULT_RERANKERS: dict[str, RerankerInfo] = {
|
||||
# ... 现有配置 ...
|
||||
|
||||
"vllm/BAAI/bge-reranker-v2-m3": RerankerInfo(
|
||||
name="BAAI/bge-reranker-v2-m3",
|
||||
base_url="http://localhost:8000/v1/rerank",
|
||||
api_key="no_api_key",
|
||||
),
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 动态配置（可选）
|
||||
|
||||
你也可以通过代码动态添加本地模型：
|
||||
|
||||
```python
|
||||
from yuxi.config import config
|
||||
from yuxi.config.static.models import EmbedModelInfo, RerankerInfo
|
||||
|
||||
# 添加本地嵌入模型
|
||||
config.embed_model_names["local/embed-model"] = EmbedModelInfo(
|
||||
name="local-embed-model",
|
||||
dimension=1024,
|
||||
base_url="http://localhost:8000/v1/embeddings",
|
||||
api_key="no_api_key",
|
||||
)
|
||||
|
||||
# 添加本地重排序模型
|
||||
config.reranker_names["local/reranker-model"] = RerankerInfo(
|
||||
name="local-reranker-model",
|
||||
base_url="http://localhost:8000/v1/rerank",
|
||||
api_key="no_api_key",
|
||||
)
|
||||
|
||||
# 保存配置
|
||||
config.save()
|
||||
```
|
||||
|
||||
#### 3. 启动模型服务
|
||||
|
||||
```bash
|
||||
# 启动嵌入模型
|
||||
vllm serve Qwen/Qwen3-Embedding-0.6B \
|
||||
--task embed \
|
||||
--dtype auto \
|
||||
--port 8000
|
||||
|
||||
# 启动重排序模型
|
||||
vllm serve BAAI/bge-reranker-v2-m3 \
|
||||
--task score \
|
||||
--dtype fp16 \
|
||||
--port 8000
|
||||
```
|
||||
**模型配置未生效**：确认模型已添加至供应商的已启用列表中。
|
||||
|
||||
@ -175,3 +175,4 @@ docker restart api-dev
|
||||
- 了解如何配置模型：阅读 [模型配置](./model-config.md)
|
||||
- 探索知识库功能：阅读 [知识库与知识图谱](./knowledge-base.md)
|
||||
- 学习智能体开发：阅读 [智能体开发](../agents/agents-config.md)
|
||||
- 深入了解配置系统：阅读 [配置系统详解](../advanced/configuration.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user