From 4b1a90a1d143f6e955a8005d7a819c191e0265e2 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Sun, 26 Apr 2026 21:43:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E9=85=8D=E7=BD=AE=E7=B3=BB?= =?UTF-8?q?=E7=BB=9F=E8=AF=A6=E8=A7=A3=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/advanced/configuration.md | 199 ++----------------------- docs/intro/model-config.md | 256 ++++++--------------------------- docs/intro/quick-start.md | 1 + 3 files changed, 56 insertions(+), 400 deletions(-) diff --git a/docs/advanced/configuration.md b/docs/advanced/configuration.md index 58186b4d..cd270d3e 100644 --- a/docs/advanced/configuration.md +++ b/docs/advanced/configuration.md @@ -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`，系统将重新生成默认配置。 diff --git a/docs/intro/model-config.md b/docs/intro/model-config.md index 9c5a3488..8f26debb 100644 --- a/docs/intro/model-config.md +++ b/docs/intro/model-config.md @@ -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": "", - "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 -``` +**模型配置未生效**：确认模型已添加至供应商的已启用列表中。 diff --git a/docs/intro/quick-start.md b/docs/intro/quick-start.md index a7794512..d01c4f7b 100644 --- a/docs/intro/quick-start.md +++ b/docs/intro/quick-start.md @@ -175,3 +175,4 @@ docker restart api-dev - 了解如何配置模型：阅读 [模型配置](./model-config.md) - 探索知识库功能：阅读 [知识库与知识图谱](./knowledge-base.md) - 学习智能体开发：阅读 [智能体开发](../agents/agents-config.md) +- 深入了解配置系统：阅读 [配置系统详解](../advanced/configuration.md)