跳转至

配置

本页说明“配置入口在哪里、什么场景应该改哪一层”，重点是帮助维护者别把运行环境、应用默认值、模型资产和控制面配置混在一起。

当前配置入口

类型 位置 主要用途
环境变量 .env、.env.local 环境差异、敏感值、端口、外部依赖地址
非敏感运行配置 config.toml 稳定默认值、特性开关、timeout、RAG / MCP / evaluation 默认参数
模型清单 ai_service/utils/models.json 模型候选项、类别和映射资产
Pydantic Settings ai_service/utils/settings.py 最终配置装配、优先级与类型校验
Compose 部署环境 .env.app.deploy.example、.env.infra.deploy.example 部署模板与容器环境注入
控制面配置 Studio / Agent Detail / System Settings Agent 级行为与运营侧运行参数

当前优先级

从 ai_service/utils/settings.py 的实现看，当前优先级是：

  1. 环境变量 / .env / .env.local
  2. config.toml
  3. 代码默认值

这意味着：

  • 环境变量是最高优先级
  • config.toml 是项目默认配置，不是最终覆盖层
  • 默认值只是兜底，不应当被当成主要配置方式

配置分层原则

环境变量

适合放：

  • 数据库连接
  • MinIO / Qdrant / 外部服务地址
  • API key / secret
  • 本机或部署环境端口差异

不适合放：

  • 大量稳定不变的算法默认值
  • Agent 级个性化行为

config.toml

适合放：

  • RAG 默认 top_k、threshold、timeout
  • MCP 默认 timeout、default budget
  • evaluation 默认策略
  • document extraction 默认模型 / retry / dpi

它的定位是“项目级默认运行参数”，而不是敏感配置仓库。

模型资产

ai_service/utils/models.json 更像模型目录，而不是系统运行开关。

适合放：

  • 模型候选清单
  • provider 归属
  • 模型类别

控制面配置

适合放：

  • Agent 的 orchestrator_key
  • model routing config
  • MCP runtime config
  • MCP response config
  • knowledge / MCP / skill mounts
  • Fusion definition 与 Agent 关联

这类配置已经是业务控制面的一部分，不应再回退成部署环境变量。

当前最容易混淆的边界

“这个值应该放环境变量，还是放 config.toml？”

判断法：

  • 如果会随环境变化，优先环境变量
  • 如果是项目默认值，优先 config.toml

“这个值应该放文件配置，还是放控制面？”

判断法：

  • 如果是全项目默认行为，放 config.toml
  • 如果是某个 Agent / 某个资源的行为，放控制面

“模型相关配置到底放哪？”

判断法：

  • 模型目录和候选项：models.json
  • 默认模型选择：config.toml
  • 某个 Agent 实际用哪个：控制面

当前值得特别关注的配置簇

配置簇 主要影响
RAG ingest、retrieval、multi-query、rerank、debug 行为
MCP default timeout、default call budget、transport 运行默认值
Evaluation runner、judge、gate、supervisor 恢复节奏
Document Extraction 默认模型、重试、图片渲染参数
CORS / public host 前端联通与环境边界

修改配置时的推荐顺序

  1. 先确认这是“环境差异”还是“项目默认值”还是“Agent 级行为”
  2. 再选择 env / TOML / 控制面
  3. 改完后跑 uv run mkdocs build
  4. 如果影响运行时行为，再做一次真实链路验证

相关页面