跳转至

配置参考

本页回答“当前项目的配置不是只有一个 .env 文件”，而是由全局运行时配置、非敏感 TOML、模型清单、数据库中的 Agent 级配置共同决定。

配置面分层

配置面 主要位置 作用 典型内容
全局环境变量 .env / deployment env 覆盖敏感值和部署差异 DATABASE_URL、OPENAI_API_KEY、MINIO_*、QDRANT_*
非敏感系统配置 config.toml 记录默认行为和基础设施地址 [database]、[rag]、[mcp]、[scheduled_tasks]
代码默认值 ai_service/utils/settings.py 提供缺省值与解析规则 stale seconds、timeout、默认 host/port
模型清单 ai_service/utils/models.json 或管理员后台 定义 provider / model catalog 聊天模型、embedding、rerank
Agent 级数据库配置 agents 相关表与 API 覆盖某个 Agent 的运行策略 model_routing_config、response_grounding_config、mcp_runtime_config
Run 级输入 API request / evaluation run / lab run 单次执行覆盖 显式传入 model_*、definition version、评测参数

真正的加载边界

全局设置层

ai_service/utils/settings.py 里的 AppSettings 聚合了多个 section settings：

  • DatabaseSettings
  • MinioSettings
  • QdrantSettings
  • EmbeddingSettings
  • RAGSettings
  • MCPSettings
  • ScheduledTasksSettings
  • RuntimeCheckpointSettings
  • AgentSettings

这些对象决定的是“系统默认运行方式”，不是某个具体 Agent 的业务策略。

非敏感 TOML 层

config.toml 主要承载不适合散落在环境变量里的默认值，例如：

  • 基础设施地址与端口
  • RAG 默认 top_k / score_threshold
  • MCP 默认 timeout / 每轮调用预算
  • scheduled task supervisor / heartbeat 参数
  • runtime checkpoint 全局开关

config.toml 不应该放：

  • 数据库密码
  • API key
  • MCP credential secret payload
  • 每个 Agent 各自的运行时策略

Agent 级持久化配置层

下面这些能力已经不是全局配置，而是按 Agent 持久化：

  • model_routing_config
  • response_grounding_config
  • mcp_runtime_config
  • mcp_response_config
  • knowledge / MCP / skill mount

这类配置变更不会改 config.toml，而是通过控制面或 API 写入数据库。

Run 级覆盖层

最终执行时，还会再被运行请求覆盖：

  • chat request 显式传入 model_name / model_provider
  • evaluation run 绑定特定 dataset version、judge policy、runtime variant
  • Fusion run 绑定特定 definition version 与 execution mode

所以解释线上行为时，不能只看 config.toml。

最常见的配置来源判断法

这是“全局系统默认”吗

如果它影响的是所有请求的基础行为，先看 ai_service/utils/settings.py 和 config.toml。

例子：

  • 数据库连接
  • MinIO / Qdrant 地址
  • RAG 默认检索参数
  • MCP 默认 timeout
  • evaluation stale heartbeat 秒数

这是“某个 Agent 的个性化行为”吗

如果它只影响一个 Agent，先查 Agent 数据库配置，而不是全局 settings。

例子：

  • 角色化模型路由
  • MCP quick match / intent gate / direct response
  • final response grounding
  • 哪些 knowledge source / MCP server / skill 被挂载

这是“单次运行”的特殊行为吗

如果它只影响某次 run，就去看请求体、checkpoint、evaluation run record 或 lab run record。

典型主题应该去哪里查

主题 先看哪里 再看哪里
数据库连接 DATABASE_URL、[database] DatabaseSettings
RAG 默认参数 [rag]、RAG_* RAG 系统文档与 retrieval debug
MCP 默认预算 / timeout [mcp]、MCP_* Agent 上的 mcp_runtime_config / mcp_response_config
模型提供商与 catalog 管理员后台模型配置 ai_service/utils/models.json fallback
定时任务 supervisor [scheduled_tasks] ai_service/services/scheduled_tasks.py
approval / checkpoint [runtime_checkpoint] orchestrator runtime + checkpoint service

容易误判的地方

  • models.json 不是唯一模型来源；数据库里的管理员模型配置优先。
  • mcp_response_config 不在全局 settings 里，而是每个 Agent 自带。
  • response_grounding_config 和 model_routing_config 也是 Agent 级，不在 config.toml。
  • evaluation 的结果解释不能只看当前系统配置，因为 run 本身会持久化 judge / gate / runtime 快照。

改动时的代码入口

想新增一个全局 section

看：

  1. ai_service/utils/settings.py
  2. config.toml.example
  3. docs/operations/configuration.md

想调整 Agent 级 MCP 运行策略

看：

  1. ai_service/orchestrator/mcp_runtime_config.py
  2. ai_service/orchestrator/mcp_response_config.py
  3. ai_service/api/routers/agents.py

想调整模型清单加载策略

看：

  1. ai_service/utils/model_loader.py
  2. ai_service/utils/models.json
  3. 管理员模型配置服务

相关页面