跳转至

配置

本项目的配置主要集中在 ai_service/utils/settings.py、根目录 config.toml 与 ai_service/utils/models.json。 敏感信息（如数据库密码）仅通过 .env 或环境变量配置，不写入 config.toml。

配置加载顺序

  1. 根目录 .env 会被 ai_service.utils.settings 自动加载。
  2. 若存在 ai_service/.env，会被模型加载器读取（override=False，不会覆盖系统环境变量）；容器部署建议优先使用平台环境变量或根目录 .env 注入。
  3. 根目录 config.toml 用于非敏感配置（如数据库 host、port、dbname）；可通过环境变量 CONFIG_FILE 指定其它路径。
  4. ai_service/.env.example 提供推荐字段模板。
  5. 运行时传入的参数（例如 API 请求中的 model_name / model_provider）优先级最高。

对聊天 Agent 补充说明：

  • CHAT_MODEL_* 与 Agent 的 model_name/model_provider/model_temperature 仍然是主模型与兼容回退。
  • model_routing_config 不放在 config.toml，而是按 Agent 存储在数据库中，通过 Agent API 或 Admin Frontend 配置。
  • response_grounding_config 不放在 config.toml，而是按 Agent 存储在数据库中，通过 Agent API 或 Admin Frontend 配置。
  • 若一次请求或一次评测显式传入 model_*，本次执行会折叠成单模型路径，不按角色路由不同模型。

config.toml（非敏感配置）

  • 位置：项目根目录 config.toml（与 pyproject.toml 同级）。可复制 config.toml.example 为 config.toml 后修改。
  • 用途：存放数据库等非敏感配置，例如 [database] 下的 backend、host、port、name、driver。不包含用户名、密码。
  • 数据库密码：仅通过环境变量 POSTGRES_USER、POSTGRES_PASSWORD 或完整连接串 DATABASE_URL 在 .env 或环境中设置。

数据库连接优先级

  1. 最高：若已设置环境变量 DATABASE_URL，直接使用，不再读取 TOML 的 [database]。
  2. 其次：若 config.toml 中存在 [database] 且 backend = "postgresql"，则用 TOML 中的 host/port/name/driver 与环境变量 POSTGRES_USER、POSTGRES_PASSWORD 拼装 PostgreSQL 连接串。
  3. 默认：无 TOML 时，使用默认 PostgreSQL 本地连接（postgresql+psycopg2://localhost:5432/chameleon_meta）。

常用环境变量

以下配置项由 Config 读取（完整字段见 API 参考）：

  • LOG_LEVEL：日志级别（默认 INFO）。
  • APP_NAME：日志器名称（默认 app）。
  • APP_ENV：运行环境标识（development / staging / production）。
  • AI_SERVICE_HOST、AI_SERVICE_PORT：本地 uv run python main.py / just run-ai-backend 启动 Uvicorn 时使用的监听地址与端口（默认 0.0.0.0:8000）。
  • DB_MIGRATION_MODE：启动迁移策略（auto / manual）。未设置时默认遵循：development -> auto，staging/production -> manual。
  • APP_INSTANCE：实例标识（用于区分多套部署；在 docker-compose.deploy.yml 与 docker-compose.infra.deploy.yml 中都可作为 Traefik router/service/middleware 命名空间，若共享同一 Traefik provider 必须保持唯一）。
  • ENV_GUARD_MODE：环境保护模式（off / warn / strict）。
  • EXPECTED_PUBLIC_HOSTS：允许访问的外部 Host 白名单（推荐逗号分隔；也兼容 JSON 数组字符串；支持 https://... 输入，运行时会归一化为 hostname）。
  • CORS_ALLOWED_ORIGINS：ai-service 的 CORS 来源白名单（推荐逗号分隔，例如 https://admin.example.com,http://localhost:5173；也兼容 JSON 数组字符串；设置为 * 表示允许任意来源）。
  • ADMIN_ACCESS_TOKEN_SECRET_KEY：后台管理员 access/refresh/challenge token 的签名密钥；生产环境必须显式配置。
  • ADMIN_ACCESS_COOKIE_SECURE：后台管理员 Cookie 是否要求 HTTPS；生产环境必须为 true。
  • ADMIN_ACCESS_BOOTSTRAP_EMAIL、ADMIN_ACCESS_BOOTSTRAP_USERNAME、ADMIN_ACCESS_BOOTSTRAP_PASSWORD：首个受保护 super_admin 的启动 bootstrap 凭据；三者要么一起配置，要么都留空。
  • ADMIN_ACCESS_BOOTSTRAP_DISPLAY_NAME：首个 bootstrap super_admin 的展示名称。
  • DATABASE_URL：数据库连接字符串。未设置时由 config.toml 的 [database] 与 POSTGRES_USER/POSTGRES_PASSWORD 拼装，或默认连接本地 PostgreSQL。
  • POSTGRES_USER、POSTGRES_PASSWORD：与 config.toml 的 [database] 配合使用时的数据库凭据（仅 PostgreSQL）。
  • ADMIN_SURFACES_ENABLE：是否启用 Dokploy 共享中间件管理界面（pgAdmin / MinIO Console / RedisInsight / Qdrant Dashboard）。
  • OPS_AUTH_HTPASSWD：共享管理界面的 Traefik BasicAuth 哈希（建议使用 htpasswd -nbB 生成）。
  • PGADMIN_DEFAULT_EMAIL、PGADMIN_DEFAULT_PASSWORD：pgAdmin 登录凭据。
  • PGADMIN_TEAM_SERVER_NAME、PGADMIN_TEAM_DB_HOST、PGADMIN_TEAM_DB_PORT、PGADMIN_TEAM_DB_NAME、PGADMIN_TEAM_DB_USER、PGADMIN_TEAM_DB_PASSWORD：pgAdmin 自动预置的 PostgreSQL 连接参数；相关值留空时回退到 POSTGRES_*。
  • MINIO_ENDPOINT：ai-service 访问 MinIO 的地址；本地开发可用 minio:9000 / localhost:9000，staging / production 应显式指向 infra host。
  • MINIO_BUCKET_RAW_DOCUMENTS：MinIO 原始文档存储桶名称（默认 raw-documents）。
  • MINIO_PUBLIC_ENDPOINT：生成预签名下载链接时使用的外部地址（例如 minio.example.com 或 https://minio.example.com）；未配置时回退为 API 代理下载。
  • MINIO_PUBLIC_SECURE：预签名下载链接是否使用 HTTPS（true/false）。
  • MINIO_PRESIGNED_EXPIRES_SECONDS：预签名下载链接过期时间（秒），默认 86400。
  • MINIO_TEAM_READONLY_USER、MINIO_TEAM_READONLY_PASSWORD：可选的共享 MinIO Console 只读账号；留空时可直接使用 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD。
  • REDIS_DEFAULT_PASSWORD：Redis 默认管理员账号（default 用户）密码，仅管理员持有。
  • REDIS_TEAM_USERNAME、REDIS_TEAM_PASSWORD：RedisInsight 使用的只读 Redis ACL 账号。
  • QDRANT_API_KEY：ai-service 访问 Qdrant 时使用的 API Key；当前 compose 不会仅因设置该变量就自动开启 Qdrant 服务级鉴权。
  • LANGFUSE_ENABLED：是否启用 Langfuse 导出（默认 false）。
  • LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY：Langfuse API 凭据。
  • LANGFUSE_HOST：Langfuse 服务地址（默认 https://us.cloud.langfuse.com）。
  • LANGFUSE_TRACING_ENVIRONMENT：写入 Langfuse 的环境标签；未设置时回退到 APP_ENV。当前 CD 默认会在 staging/prod 部署时分别写入 staging / production。
  • LANGFUSE_RELEASE：可选的发布版本标签。当前 CD 默认会在 staging 写入 GITHUB_SHA，production 写入发布 tag（GITHUB_REF_NAME），rollback 写入 ROLLBACK_TAG。
  • LANGFUSE_SAMPLE_RATE：Langfuse 采样率（0.0 - 1.0）。
  • AGENT_SYSTEM_PROMPT_MAX_LENGTH：Agent system_prompt 的最大字符数；默认 30000。
  • CHAT_MODEL_NAME：默认聊天模型名称。
  • CHAT_MODEL_PROVIDER：默认模型提供商。
  • CHAT_MODEL_TEMPERATURE：默认温度。
  • EMBEDDING_PROVIDER：Embedding 提供商（sentence_transformers 或 dashscope）。
  • EMBEDDING_BACKEND_TYPE：Embedding 后端类型（api 或 local，默认 api）。
  • EMBEDDING_MODEL：Embedding 模型名称。
  • EMBEDDING_DIM：Embedding 维度。
  • RERANK_ENABLED：是否启用检索后重排。
  • RERANK_MODEL：重排模型（默认 qwen3-rerank）。
  • BACKUP_MODE：备份模式（tiered / hot / cold / all）。tiered 为分层模式，仅备份 PG + 增量同步 MinIO 到 S3。
  • BACKUP_COMPOSE_FILE：备份脚本使用的 Compose 文件路径。
  • BACKUP_LOCAL_STAGE_DIR：备份临时工作目录。
  • BACKUP_LOCAL_ARCHIVE_DIR：备份归档目录。
  • BACKUP_REMOTE_DIR：远端/第二副本目录（可选）。
  • BACKUP_REMOTE_RSYNC_TARGET：通过 rsync 推送的远程目标（可选）。
  • BACKUP_RETENTION_DAYS：备份保留天数（默认 30）。
  • BACKUP_ENCRYPTION_ENABLED：是否启用归档加密（默认 true）。
  • BACKUP_KEEP_PLAINTEXT_ARCHIVE：加密后是否保留明文归档（默认 false）。
  • BACKUP_COLD_STOP_SERVICES：冷备时是否自动停止 postgres/minio/qdrant（默认 true）。
  • BACKUP_RESTORE_PREFER_COLD：恢复时优先使用冷备卷快照（默认 false）。
  • BACKUP_HEALTHCHECK_URL：恢复完成后的健康检查地址（默认 http://localhost:8000/healthz）。
  • BACKUP_ENCRYPTION_PASSPHRASE：备份归档加密口令（建议仅放在密钥管理系统）。
  • BACKUP_CRON_SCHEDULE：backup-cron 容器的定时表达式（默认 0 18 * * *，即 UTC+8 凌晨 2 点）。
  • BACKUP_S3_ENABLED：是否启用 S3 兼容存储上传（默认 false）。
  • BACKUP_S3_ENDPOINT：S3 兼容端点地址（例如 Backblaze B2：https://s3.us-west-004.backblazeb2.com）。
  • BACKUP_S3_BUCKET：S3 桶名称。
  • BACKUP_S3_PREFIX：S3 对象前缀（默认 backups）。
  • BACKUP_S3_SKIP_UPLOAD：临时禁用 S3 上传（默认 false）。
  • BACKUP_S3_MINIO_PREFIX：MinIO 增量镜像在 S3 中的前缀（默认 minio-mirror）。
  • BACKUP_S3_ACCESS_KEY_ID：S3 访问密钥 ID（建议仅放在密钥管理系统）。
  • BACKUP_S3_SECRET_ACCESS_KEY：S3 访问密钥（建议仅放在密钥管理系统）。

共享中间件管理界面配置

docker-compose.infra.deploy.yml 现在支持一组受保护的团队共享管理入口：

  • db.<BASE_DOMAIN> -> pgAdmin
  • minio-console.<BASE_DOMAIN> -> MinIO Console
  • redis.<BASE_DOMAIN> -> RedisInsight
  • qdrant.<BASE_DOMAIN> -> Qdrant Dashboard

配置原则：

  • 外层统一由 OPS_AUTH_HTPASSWD 提供 Traefik BasicAuth。
  • 内层使用服务自身账号体系：
  • PostgreSQL 默认预置数据库连接；若未配置 PGADMIN_TEAM_DB_*，自动回退到 POSTGRES_*
  • MinIO 默认可直接使用 root 账号；如需共享只读用户，再额外配置 MINIO_TEAM_READONLY_*
  • Redis 在容器启动时渲染管理员 / 只读 ACL 用户
  • Qdrant 默认仅依赖外层 BasicAuth；若你在仓库外单独开启 Qdrant 服务级鉴权，再同步配置 QDRANT_API_KEY
  • ADMIN_SURFACES_ENABLE 默认建议保持 false，准备好 DNS 与凭据后再开启。

备份配置建议（非敏感放 TOML）

建议将以下非敏感备份配置放在 config.toml 的 [backup]：

[backup]
cron_schedule = "0 18 * * *"  # daily at 02:00 UTC+8
mode = "all"
compose_file = "docker-compose.infra.deploy.yml"
local_stage_dir = "data/backups/stage"
local_archive_dir = "data/backups/archive"
remote_dir = ""
remote_rsync_target = ""
retention_days = 30
encryption_enabled = true
keep_plaintext_archive = false
cold_stop_services = true
restore_prefer_cold = false
healthcheck_url = "http://localhost:8000/healthz"
restore_report_dir = "data/backups/restore-reports"
# S3 兼容远程存储（Backblaze B2、AWS S3、Cloudflare R2 等）
# 凭据通过 BACKUP_S3_ACCESS_KEY_ID / BACKUP_S3_SECRET_ACCESS_KEY 环境变量配置
s3_enabled = false
s3_endpoint = ""          # 例如 "https://s3.us-west-004.backblazeb2.com"
s3_bucket = ""            # 例如 "my-aibot-backups"
s3_prefix = "backups"
s3_skip_upload = false
s3_minio_prefix = "minio-mirror"   # MinIO 增量镜像在 S3 中的前缀

说明：

  • compose_file = "docker-compose.infra.deploy.yml" 是仓库内统一的备份/恢复默认目标，对应独立 infra host。
  • 本地一体化开发如果要操作 just docker-infra 拉起的栈，请显式覆盖为 docker-compose.infra.yml。

优先级说明（备份脚本）：

  1. 命令行参数（如 --mode）
  2. 环境变量（BACKUP_*）
  3. config.toml [backup]
  4. 脚本内默认值

远程复制规则：

  • 只有在 skip_remote_copy = false 且 remote_dir 或 remote_rsync_target 至少配置一个时，才会执行远程复制。
  • 若两者都为空，只会生成本地归档。

CI/CD 配置（GitHub Actions）

CI/CD 的运行配置主要来自 GitHub Environments / Secrets 与 Repository Variables，不应写入仓库文件。

Repository Secrets（仓库级）

  • REGISTRY_USERNAME：远程镜像仓库 registry.zata.cafe 登录用户名
  • REGISTRY_PASSWORD：远程镜像仓库 registry.zata.cafe 登录密码

Environment Secrets（按环境分别配置）

staging Environment：

  • DOKPLOY_API_KEY：staging 所在 Dokploy 服务器的 API Key
  • DOKPLOY_STAGING_APP_DEPLOY_HOOK：staging app 发布触发 hook
  • DOKPLOY_STAGING_INFRA_DEPLOY_HOOK：staging infra 发布触发 hook

production Environment：

  • DOKPLOY_API_KEY：production 所在 Dokploy 服务器的 API Key
  • DOKPLOY_PROD_APP_DEPLOY_HOOK：production app 发布触发 hook
  • DOKPLOY_PROD_INFRA_DEPLOY_HOOK：production infra 发布触发 hook
  • PROD_HEALTHCHECK_URL：production app 发布或 rollback 后的健康检查地址

Environment Variables（按环境分别配置）

staging Environment：

  • DOKPLOY_STAGING_APP_COMPOSE_ID：staging app compose ID
  • DOKPLOY_STAGING_INFRA_COMPOSE_ID：staging infra compose ID
  • DOKPLOY_API_BASE_URL：staging 所在 Dokploy API 基础地址（例如 https://dokploy-staging.example.com/api）

production Environment：

  • DOKPLOY_PROD_APP_COMPOSE_ID：production app compose ID
  • DOKPLOY_PROD_INFRA_COMPOSE_ID：production infra compose ID
  • DOKPLOY_API_BASE_URL：production 所在 Dokploy API 基础地址（例如 https://dokploy-prod.example.com/api）

说明：

  • staging 与 production 部署在不同服务器，DOKPLOY_API_KEY 和 DOKPLOY_API_BASE_URL 须在各自 Environment 中分别配置。
  • compose ID 为非敏感标识符，配置为 Variable 便于在 Actions 日志中可见、在 GitHub UI 中可读。
  • staging 和 production 环境下，app / infra 各自的 compose ID 都应显式配置，不再从 deploy hook 推断 composeId。
  • DOKPLOY_API_BASE_URL 会自动规范为 .../api。
  • push main 与 push tag v* 只会更新 app compose；infra compose 通过 workflow_dispatch 手动触发。

补充：workflow 更新 compose env 时会写入并校验当前环境的 APP_ENV、APP_INSTANCE、ENV_GUARD_MODE、EXPECTED_PUBLIC_HOSTS。

当前发布链路不在 GitHub Actions 中单独执行 Alembic 迁移，而是由部署后的 ai-service 在启动阶段（DB_MIGRATION_MODE=auto）执行迁移。

Repository Variable

  • IMAGE_NAMESPACE：镜像命名空间，默认 aibot。

镜像命名规则

CD 工作流默认推送以下形式的镜像：

registry.zata.cafe/<IMAGE_NAMESPACE>/<service>:<GIT_SHA>

其中 <service> 包含：

  • ai-service
  • demo-backend
  • demo-frontend
  • admin-frontend
  • docs-site
  • backup-cron

Bases: BaseSettings

应用主配置 - 聚合所有子配置。

属性：

名称 类型 描述
app_name str

应用名称。
log_level str

日志级别。
app_env Literal['development', 'staging', 'production']

运行环境标识。
app_instance str

运行实例标识。
env_guard_mode EnvironmentGuardMode

环境保护模式（off/warn/strict）。
expected_public_hosts list[str]

允许访问的外部 Host 白名单。
cors_allowed_origins list[str]

CORS 允许来源（支持逗号分隔字符串或 list 输入）。
postgres_user str

PostgreSQL 用户名。
postgres_password SecretStr

PostgreSQL 密码。
database_url str

完整数据库 URL 覆盖。
minio_access_key str

MinIO 访问密钥。
minio_secret_key SecretStr

MinIO 密钥。
minio_root_user str

Docker MinIO root 用户。
minio_root_password SecretStr

Docker MinIO root 密码。
database DatabaseSettings

数据库子配置。
chat_model ChatModelSettings

聊天模型子配置。
minio MinioSettings

MinIO 子配置。
qdrant QdrantSettings

Qdrant 子配置。
embedding EmbeddingSettings

Embedding 子配置。
rerank RerankSettings

Rerank 子配置。
multi_query MultiQuerySettings

Multi-Query RAG 扩展子配置。
rag RAGSettings

RAG 检索默认参数子配置。
chunking ChunkingSettings

分块子配置。
timeouts TimeoutSettings

超时子配置。
mcp MCPSettings

MCP 出站能力配置。
skill SkillSettings

Skill 运行时配置。
fusion FusionSettings

Fusion 运行时配置。
scheduled_tasks ScheduledTasksSettings

定时任务运行时配置。
runtime_checkpoint RuntimeCheckpointSettings

运行时 checkpoint 配置。
agent_memory AgentMemorySettings

Agent 长期记忆配置。
langfuse LangfuseSettings

Langfuse 观测导出配置。
release ReleaseSettings

部署发布元数据。
admin_access AdminAccessSettings

后台身份与会话配置。
agent AgentSettings

Agent 通用配置。
agent_types AgentTypesSettings

智能体类型配置。
base_dir Path

项目根目录。
log_dir Path

日志目录。
log_file Path

日志文件路径。

resolved_database_url property 

resolved_database_url

解析最终 DATABASE_URL：env var > TOML + credentials > default。

返回：

名称 类型 描述
str str

最终的数据库连接 URL。

resolved_minio_access_key property 

resolved_minio_access_key

MinIO access key: MINIO_ACCESS_KEY > MINIO_ROOT_USER > default。

返回：

名称 类型 描述
str str

解析后的 MinIO access key。

resolved_minio_secret_key property 

resolved_minio_secret_key

MinIO secret key: MINIO_SECRET_KEY > MINIO_ROOT_PASSWORD > default。

返回：

名称 类型 描述
str str

解析后的 MinIO secret key。

ensure_log_directory 

ensure_log_directory()

确保日志目录存在。

引发：

类型 描述
OSError

当无法创建目录时抛出。

settings_customise_sources classmethod 

settings_customise_sources(settings_cls, **kwargs)

配置源优先级：init args > env vars > .env > TOML [app] > defaults。

嵌套子模型各自读取 config.toml 对应 section。

参数：

名称 类型 描述 默认
settings_cls type[BaseSettings]

Settings 类。

 必需
**kwargs Any

默认源参数。

 {}

返回：

类型 描述
tuple[Any, ...]

tuple[Any, ...]: 配置源元组，按优先级排列。

Fusion 运行时配置

可在 config.toml 中新增 [fusion]，用于控制 Fusion background run 的心跳与 stale 回收：

[fusion]
dispatcher_idle_seconds = 1.0
supervisor_interval_seconds = 5.0
worker_stale_seconds = 900
worker_heartbeat_interval_seconds = 60.0

说明：

  • dispatcher_idle_seconds：dispatcher 空闲轮询间隔。
  • supervisor_interval_seconds：supervisor 保活 dispatcher 并执行 stale recovery 的周期。
  • worker_stale_seconds：判定 queued / pending / running Fusion run 已失活并自动标记为 failed 的阈值。
  • worker_heartbeat_interval_seconds：执行中的 Fusion run 刷新 worker_heartbeat_at 的周期。

环境变量前缀为 FUSION_，例如：

  • FUSION_WORKER_STALE_SECONDS
  • FUSION_WORKER_HEARTBEAT_INTERVAL_SECONDS
  • FUSION_DISPATCHER_IDLE_SECONDS
  • FUSION_SUPERVISOR_INTERVAL_SECONDS

定时任务配置

可在 config.toml 中新增 [scheduled_tasks]，用于控制 conversation-defined timer runtime：

[scheduled_tasks]
enabled = false
dispatcher_idle_seconds = 1.0
supervisor_interval_seconds = 5.0
worker_stale_seconds = 900
worker_heartbeat_interval_seconds = 60.0
defer_retry_seconds = 300
max_list_records = 100

说明：

  • enabled：是否启用后台 timer scheduler；关闭时不会执行 due task，但 Admin API 仍可查看已持久化任务。
  • dispatcher_idle_seconds：dispatcher 空闲轮询间隔。
  • supervisor_interval_seconds：supervisor 保活 dispatcher 并回收 stale lease 的周期。
  • worker_stale_seconds：判定 running task / run 心跳过期的阈值。
  • worker_heartbeat_interval_seconds：单个执行中的 run 刷新 heartbeat 的周期。
  • defer_retry_seconds：conflict_policy=defer 或 recurring task 失败后的延后重试窗口。
  • max_list_records：服务层默认列表窗口上限。

环境变量前缀为 SCHEDULED_TASKS_，例如：

  • SCHEDULED_TASKS_ENABLED
  • SCHEDULED_TASKS_WORKER_STALE_SECONDS
  • SCHEDULED_TASKS_DEFER_RETRY_SECONDS

MCP 配置（出站能力）

可在 config.toml 中新增 [mcp]，用于控制出站 MCP 能力：

[mcp]
enabled = true
max_tool_rounds = 3
history_user_message_window = 3
default_timeout_ms = 10000
default_max_calls_per_turn = 3
default_encryption_key_id = "mcp-key-v1"

建议通过环境变量提供密钥：

  • MCP_SECRET_KEY：MCP 凭据加密主密钥（必填，生产环境必须覆盖默认值）
  • MCP_DEFAULT_ENCRYPTION_KEY_ID：默认密钥版本标识
  • MCP_REDACT_KEYS：审计脱敏关键字数组（推荐逗号分隔，也兼容 JSON 数组字符串）

说明：secret_key 不应写入 config.toml，应放在 .env 或部署环境密钥管理系统中。

补充说明：

  • history_user_message_window 控制 MCP 在工具选择和参数推断时可复用的最近 user 历史消息条数。
  • 当前默认值是 3，只影响 MCP 的有界上下文，不改变最终 LLM 回复对完整 conversation_history 的使用方式。
  • MCP 的产品级 direct return / quick-match / intent-gate 已迁移到 Agent 配置字段 mcp_response_config，控制面入口是 Admin Frontend 的 Agent Responses 工作区或 Agent API。
  • 查询前门禁关键词匹配的主入口是 Agent settings 的 mcp_response_config.intent_gate_rules[]，而不是全局 ai_service/utils/settings.py / [mcp]。
  • [mcp] 仍负责运行时默认值，例如总轮数、历史窗口、默认超时、每轮调用预算与默认加密 key。

Agent 级 MCP 响应与前门禁控制面

  • mcp_response_config 不放在 config.toml，而是保存在每个 chat Agent 上。
  • direct_response_rules[]：
  • 绑定 Agent 已挂载的 mcp_server_id + tool_name
  • 支持 raw_json、json_subset、text
  • wrap_json_code_block=true 时，JSON 类输出会包成 Markdown ```json fenced block
  • json_subset / text 可配置 selected_fields[]、omit_empty_fields、prefix_text、suffix_text
  • quick_match_rules[]：
  • 仅在 POST /stream 的 message_type=user_chat 上生效
  • 通过前缀命令直接触发一次 MCP 调用，例如 #get_tracking123556
  • 可通过 response_rule_key 复用 direct-response formatter；若不配置则默认返回 raw_json
  • intent_gate_rules[]：
  • tool_capability 现在允许管理员填写任意非空 capability 标签，不再限制为内建枚举
  • 当前只有 tracking 具备内建运行时特化；其它 capability 仅作为挂载级 intent gate 标签使用
  • 对自定义 capability，运行时会把它与挂载上的 tool_capability 对齐，并用该 rule 的 keywords[] / regex_patterns[] 对“当前用户消息”做一次挂载前门禁
  • 若某个挂载声明了自定义 capability，但 Agent 没有为它启用对应 rule，运行时保持旧行为，不额外拦截该挂载
  • allow_contextual_follow_up 与内建默认 matcher 目前仍主要服务 tracking 运行时
  • Agent 的 MCP mount 现在还支持可选 tool_capability 字段：
  • 配置入口是管理员 Agent 详情页的 Integrations / MCP Servers 挂载区域
  • 当前活跃的 Studio 界面支持在新增挂载时填写 capability，并在挂载表格中查看当前值
  • 建议把它看作“这个挂载代表什么业务域”的标签，例如 tracking、shipment_eta、booking_status
  • Agent 页面还支持 POST /agents/{agent_id}/mcp-response-preview 的真实预览能力，用于先跑一次 MCP，再按字段勾选和格式调优。

Agent 级最终回复防幻觉控制面

  • response_grounding_config 不放在 config.toml，而是保存在每个 chat Agent 上。
  • 当前字段：
  • enabled
  • policy_version
  • mode：balanced / strict
  • allow_general_knowledge
  • low_confidence_behavior：best_effort / ask_for_clarification / decline
  • structured_output_failure_behavior：fallback_to_text / ask_for_clarification / decline
  • 当前默认聊天运行时会在最终回复阶段优先尝试结构化输出，并把结果归类为 answer、ask_for_clarification、decline。
  • strict 模式适合高风险或强事实约束场景；当 prompt 中已经嵌入 RAG / Skill / MCP 结果时，运行时会更保守地拒绝未显式基于这些上下文的最终回答。
  • allow_general_knowledge=false 适合“只能基于挂载知识和工具结果回答”的 Agent。

Agent 配置

可在 config.toml 中新增 [agent]，用于管理 Agent 通用限制：

[agent]
system_prompt_max_length = 30000
judge_prompt_max_length = 30000

说明：

  • system_prompt_max_length 控制 POST /agents 与 PATCH /agents/{agent_id} 接口接受的 system_prompt 最大字符数。
  • judge_prompt_max_length 控制 POST /agents 与 PATCH /agents/{agent_id} 接口接受的 judge_prompt 最大字符数。judge_prompt 用于管理员自定义 evaluation 的 LLM Judge system prompt。
  • 数据库存储列仍为 Text；当前有效限制由 API 校验与该配置项共同决定。

Agent 级聊天模型路由

角色化模型路由不通过 config.toml 配置，而是保存在 chat Agent 的 model_routing_config 中：

  • 顶层控制：
  • enabled
  • policy_version
  • collapse_to_explicit_override
  • fallback_to_primary_model
  • 角色槽位：
  • tool_call_model
  • general_model
  • complex_task_model
  • reasoning_model

建议：

  • 主模型三元组始终保留可用值，作为空槽位回退和显式覆盖折叠后的执行模型。
  • 通过 GET /models 返回的 category 与 description 字段，为不同角色挑选更合适的模型，而不是在前端硬编码候选项。

Langfuse 配置

可在 config.toml 中新增 [langfuse]，用于控制外部 trace 导出：

[langfuse]
enabled = false
host = "https://us.cloud.langfuse.com"
sample_rate = 1.0
tracing_environment = "development"
release = ""
capture_prompts = true
capture_responses = true
capture_tool_payloads = true
force_flush_on_request_end = false
flush_at = 512
flush_interval = 5.0

建议通过环境变量提供凭据：

  • LANGFUSE_PUBLIC_KEY
  • LANGFUSE_SECRET_KEY

说明：

  • 当前实现只在 ai_service 中导出 Langfuse traces，不影响 demo-backend 或前端。
  • Langfuse 导出采用 best-effort 语义：关闭、缺少凭据、SDK 不可用或上游故障都不会阻断聊天请求。
  • 现有数据库观测仍然是内部事实源；Langfuse 仅作为外部排障视图，turn 上下文接口会暴露可选的 langfuse_trace_url。

Skill Runtime 配置

可在 config.toml 中新增 [skill]，用于控制 Skill 运行时开关与默认策略：

[skill]
enabled = true
max_execution_rounds = 3
default_timeout_ms = 10000
default_max_calls_per_turn = 3

可通过环境变量覆盖：

  • SKILL_ENABLED：是否启用 Skill 运行时链路
  • SKILL_MAX_EXECUTION_ROUNDS：每轮对话的最大 Skill 执行轮次
  • SKILL_DEFAULT_TIMEOUT_MS：Skill 挂载默认超时
  • SKILL_DEFAULT_MAX_CALLS_PER_TURN：Skill 挂载默认调用预算
  • SKILL_REDACT_KEYS：Skill 审计脱敏关键字（逗号分隔或 JSON 数组）

说明：skill.enabled=false 可作为灰度回滚开关，关闭后不影响现有 MCP 链路。

模型配置（管理员后台 / models.json）

  • 运行时优先使用管理员后台写入数据库的 provider / model 配置。
  • 当数据库里还没有任何 provider 配置时，回退到 ai_service/utils/models.json。
  • 配置内容包括提供商与模型列表，以及可选 api_key_env、加密存储的 api_key、base_url 等信息。
  • 管理员后台支持对已保存的模型执行一次最小测试调用，用于验证模型名、鉴权和 base URL 是否可用。
  • 当模型名称在多个提供商中重复时，建议显式传入 provider。

Embedding / Rerank 类别约束

  • Embedding 模型必须属于 text_embeddings 类别。
  • Rerank 模型必须属于 rerank_models 类别。
  • 若误将 qwen3-rerank 配置到 [embedding].model，启动或首次加载时会抛出明确错误。

推荐配置模板

在线（DashScope）

[embedding]
backend_type = "api"
provider = "dashscope"
model = "text-embedding-v4"
dim = 1536
offline_mode = false
model_dir = "resources/models"

[rerank]
enabled = true
provider = "dashscope"
model = "qwen3-rerank"
top_k = 20

[rag]
top_k = 5
score_threshold = 0.3

离线（SentenceTransformers）

[embedding]
backend_type = "local"
provider = "sentence_transformers"
model = "sentence-transformers/all-MiniLM-L6-v2"
dim = 384
offline_mode = true
model_dir = "resources/models"

[rerank]
enabled = false

[rag]
top_k = 5
score_threshold = 0.3

Qdrant 安全迁移配置

为避免 embedding 维度切换时覆盖旧向量，建议开启指纹集合命名：

[qdrant]
collection_name = "document_vectors"
use_embedding_fingerprint_collection = true
dual_read_enabled = false
read_fallback_collection_names = []

切换阶段可启用灰度双读：

[qdrant]
dual_read_enabled = true
read_fallback_collection_names = [
  "document_vectors__sentence-transformers-all-minilm-l6-v2__384"
]

当 [embedding] 中出现未知字段时，系统会输出 warning（包含 section 与字段名），避免静默失效。

补充：QDRANT_READ_FALLBACK_COLLECTION_NAMES 作为环境变量时，推荐使用逗号分隔（如 a,b），也兼容 JSON 数组字符串（如 ["a","b"]）。

如需自定义模型清单，可通过 config_path 参数覆盖默认路径。

日志与数据库

  • 日志输出：控制台 + 按日期命名的文件，例如 logs/app-2026-03-20.log。
  • 数据库：通过 config.toml 或 DATABASE_URL 配置 PostgreSQL 连接；未配置时默认连接本地 PostgreSQL。

如需覆盖连接，请在 .env 中设置 DATABASE_URL 或调整 config.toml 与 LOG_LEVEL 等配置项。