配置

本项目的配置主要集中在 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）优先级最高。

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）。
• DATABASE_URL：数据库连接字符串。未设置时由 config.toml 的 [database] 与 POSTGRES_USER/POSTGRES_PASSWORD 拼装，或默认连接本地 PostgreSQL。
• POSTGRES_USER、POSTGRES_PASSWORD：与 config.toml 的 [database] 配合使用时的数据库凭据（仅 PostgreSQL）。
• 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）。

CI/CD 配置（GitHub Actions）

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

必需 Secrets（发布链路）

• REGISTRY_USERNAME：远程镜像仓库 registry.zata.cafe 登录用户名
• REGISTRY_PASSWORD：远程镜像仓库 registry.zata.cafe 登录密码
• DOKPLOY_PROD_DEPLOY_HOOK：生产发布触发 hook
• PROD_HEALTHCHECK_URL：生产发布后的健康检查地址

可选 Secrets

• DOKPLOY_STAGING_DEPLOY_HOOK：staging 阶段自动触发 hook（未配置则跳过）

Repository Variable

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

镜像命名规则

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

registry.zata.cafe/<IMAGE_NAMESPACE>/<service>:<GIT_SHA>
registry.zata.cafe/<IMAGE_NAMESPACE>/<service>:main-latest

其中 <service> 包含：

• ai-service
• demo-backend
• demo-frontend
• admin-frontend

Bases: BaseSettings

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

属性：

名称	类型	描述
app_name	str	应用名称。
log_level	str	日志级别。
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 子配置。
chunking	ChunkingSettings	分块子配置。
timeouts	TimeoutSettings	超时子配置。
mcp	MCPSettings	MCP 出站能力配置。
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)

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

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

参数：

名称	类型	描述	默认
settings_cls	type[BaseSettings]	Settings 类。	必需
**kwargs	Any	默认源参数。	{}

返回：

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

MCP 配置（出站能力）

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

[mcp]
enabled = true
max_tool_rounds = 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 或部署环境密钥管理系统中。

模型配置（models.json）

• 路径：ai_service/utils/models.json
• 内容：提供商与模型列表、可选 api_key_env、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

离线（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

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 与字段名），避免静默失效。

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

日志与数据库

• 日志输出：控制台 + logs/app.log。
• 数据库：通过 config.toml 或 DATABASE_URL 配置 PostgreSQL 连接；未配置时默认连接本地 PostgreSQL。

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