186 lines
4.8 KiB
Markdown
186 lines
4.8 KiB
Markdown
# 配置系统详解
|
||
|
||
## 概述
|
||
|
||
Yuxi-Know 从 v0.3.x 版本开始采用了全新的配置系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等现代化特性。
|
||
|
||
## 架构设计
|
||
|
||
### 配置层次结构
|
||
|
||
```
|
||
配置系统架构
|
||
├── 默认配置 (代码定义)
|
||
│ ├── src/config/static/models.py (模型配置)
|
||
│ └── src/config/app.py (应用配置)
|
||
├── 用户配置 (TOML 文件)
|
||
│ └── saves/config/base.toml (仅保存用户修改)
|
||
└── 环境变量 (运行时覆盖)
|
||
└── .env 文件
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
#### 1. Config 类 (`src/config/app.py`)
|
||
|
||
主配置类，继承自 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/deepseek-ai/DeepSeek-V3.2-Exp")
|
||
embed_model: str = Field(default="siliconflow/BAAI/bge-m3")
|
||
|
||
# 运行时状态 (不持久化)
|
||
model_provider_status: dict[str, bool] = Field(exclude=True)
|
||
```
|
||
|
||
#### 2. 模型配置类 (`src/config/static/models.py`)
|
||
|
||
定义了三种类型的模型配置：
|
||
|
||
- **ChatModelProvider**: 聊天模型提供商
|
||
- **EmbedModelInfo**: 嵌入模型信息
|
||
- **RerankerInfo**: 重排序模型信息
|
||
|
||
```python
|
||
class ChatModelProvider(BaseModel):
|
||
name: str = Field(..., description="提供商显示名称")
|
||
url: str = Field(..., description="提供商文档或模型列表 URL")
|
||
base_url: str = Field(..., description="API 基础 URL")
|
||
default: str = Field(..., description="默认模型名称")
|
||
env: str = Field(..., description="API Key 环境变量名")
|
||
models: list[str] = Field(default_factory=list, description="支持的模型列表")
|
||
```
|
||
|
||
添加配置：
|
||
|
||
|
||
```python
|
||
# 1. 在 DEFAULT_CHAT_MODEL_PROVIDERS 中添加
|
||
"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. 在 .env 中配置 API Key
|
||
# NEW_PROVIDER_API_KEY=your_api_key
|
||
|
||
# 3. 重启服务或重新加载配置
|
||
```
|
||
|
||
## 配置管理特性
|
||
|
||
系统只会保存用户修改过的配置项：
|
||
|
||
```python
|
||
# 用户只修改了 enable_reranker
|
||
config.enable_reranker = True
|
||
config.save() # 只保存 enable_reranker 到 TOML 文件
|
||
|
||
# TOML 文件内容
|
||
# enable_reranker = true
|
||
```
|
||
|
||
### 默认模型配置 (`src/config/static/models.py`)
|
||
|
||
包含所有支持的模型提供商的默认配置，开发者可以直接修改此文件添加新的模型：
|
||
|
||
```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-V3.2-Exp",
|
||
env="SILICONFLOW_API_KEY",
|
||
models=[
|
||
"deepseek-ai/DeepSeek-V3.2-Exp",
|
||
"Qwen/Qwen3-235B-A22B-Instruct-2507",
|
||
# ...
|
||
],
|
||
),
|
||
# 更多提供商...
|
||
}
|
||
```
|
||
|
||
### 用户配置 (`saves/config/base.toml`)
|
||
|
||
只包含用户修改过的配置项，使用 TOML 格式：
|
||
|
||
```toml
|
||
# 用户只修改了这些配置项
|
||
enable_reranker = true
|
||
default_agent_id = "MyCustomAgent"
|
||
enable_content_guard = true
|
||
|
||
# 模型配置修改
|
||
[model_names.siliconflow]
|
||
models = [
|
||
"deepseek-ai/DeepSeek-V3.2-Exp",
|
||
"custom-model-name",
|
||
]
|
||
```
|
||
|
||
## 高级配置
|
||
|
||
### 动态配置更新
|
||
|
||
```python
|
||
from src.config import config
|
||
|
||
# 更新配置
|
||
config.enable_reranker = True
|
||
config.default_agent_id = "CustomAgent"
|
||
|
||
# 更新模型列表
|
||
config.model_names["siliconflow"].models.append("new-model")
|
||
|
||
# 保存配置
|
||
config.save()
|
||
|
||
# 或者只保存特定提供商的模型配置
|
||
config._save_models_to_file("siliconflow")
|
||
```
|
||
|
||
### 配置验证
|
||
|
||
```python
|
||
# 验证配置
|
||
from src.config import config
|
||
|
||
# 检查模型提供商可用性
|
||
for provider, status in config.model_provider_status.items():
|
||
print(f"{provider}: {'✅' if status else '❌'}")
|
||
|
||
# 获取可用模型列表
|
||
available_models = config.get_model_choices()
|
||
available_embed_models = config.get_embed_model_choices()
|
||
available_rerankers = config.get_reranker_choices()
|
||
```
|
||
|
||
### 配置导出
|
||
|
||
```python
|
||
# 导出完整配置（包含运行时状态）
|
||
full_config = config.dump_config()
|
||
|
||
# 导出用户配置（仅保存到文件的部分）
|
||
user_config = {
|
||
field: getattr(config, field)
|
||
for field in config._user_modified_fields
|
||
}
|