2026Technology-Competition/docs/config-design.md

统一配置设计

版本: v1.0 | 日期: 2026-07-30 | 状态: 初版

本文档统一定义本项目的全部配置项：config/inference.yaml、config/rag.yaml、config/app.yaml、.env 环境变量及 Docker Compose 草案。所有配置项一处定义、一处生效，避免散落。

---

目录

1. 配置层次与加载顺序
2. 环境变量（.env）
3. app.yaml（应用级）
4. inference.yaml（推理引擎）
5. rag.yaml（RAG 层）
6. Docker Compose 草案
7. 配置校验与脱敏

---

1. 配置层次与加载顺序

优先级（高 → 低）:
  1. 环境变量（.env / 系统环境）      ← API Key 等敏感项
  2. 环境特定 YAML（config/*.yaml）   ← 模型/路径/阈值
  3. 代码默认值                       ← 兜底

加载方式:
  pydantic-settings 统一加载
  ├── BaseSettings 合并 .env + 环境变量
  └── YAML 文件经 pydantic 模型校验后加载

原则：

• 敏感项只走环境变量（API Key），不落入 YAML、不硬编码（AGENTS.md 要求）
• YAML 只放非敏感配置（模型名、路径、阈值、开关）
• 每个配置项有默认值；YAML 缺失时用默认值，不阻塞启动

---

2. 环境变量（.env）

# ── LLM Provider ─────────────────────────────────
DEEPSEEK_API_KEY=sk-xxx              # DeepSeek 主模型
QWEN_API_KEY=sk-xxx                  # Qwen 备用模型
VISION_API_KEY=sk-xxx                # Vision 模型（可复用主 Key）
LLM_BASE_URL=https://api.deepseek.com # 可选：自定义 base_url

# ── 部署 ─────────────────────────────────────────
APP_ENV=dev                          # dev | prod
APP_HOST=0.0.0.0
APP_PORT=8000
DATA_DIR=/data                       # 用户数据根目录
CONFIG_DIR=/config                   # YAML 配置目录

# ── 队列（可选，默认 InMemory）───────────────────
QUEUE_BACKEND=memory                 # memory | redis | valkey
REDIS_URL=redis://queue:6379/0       # 切换队列时使用

变量	必填	默认	说明
DEEPSEEK_API_KEY	是	—	主模型 Key，缺失则相关功能不可用
QWEN_API_KEY	否	—	备用模型 Key，缺失时降级为「无备用」
VISION_API_KEY	否	同主 Key	Vision 模型 Key
QUEUE_BACKEND	否	memory	队列实现选择

---

3. app.yaml（应用级）

# config/app.yaml
app:
  name: genesis
  version: "1.0"
  timezone: Asia/Tokyo

server:
  max_upload_mb: 100          # 上传文件大小限制
  allowed_extensions:          # 允许的扩展名
    - .xlsx
    - .xls
    - .docx
    - .pptx
    - .java
    - .xml
    - .yml

session:
  sqlite_path: /data/db/genesis.db   # SQLite 会话库
  snapshot_dir: /data/db/snapshots   # 中间成果物快照目录

paths:
  user_root: /data/users
  shared_root: /data/shared

task_queue:
  backend: memory              # memory | redis | valkey（对应 QUEUE_BACKEND）
  redis_url: ${REDIS_URL}      # 环境变量引用
  timeout_sec: 600             # 任务最长执行时间
  retry_default: 2             # 任务默认重试次数

---

4. inference.yaml（推理引擎）

对应 docs/agent-runtime-design.md §2。全部 LLM 相关配置集中于此：

# config/inference.yaml
models:
  primary:
    provider: deepseek          # deepseek | qwen | openai_compatible
    name: deepseek-chat         # 模型名
    temperature: 0.2
    max_tokens: 4096
    timeout_sec: 60
    retry_backoff: [1, 3, 7]    # 指数退避（秒）

  fallback:
    provider: qwen
    name: qwen-max
    temperature: 0.2
    max_tokens: 4096

  vision:
    provider: deepseek
    name: deepseek-vl            # Vision 模型（ImageAnalyzer 使用）
    timeout_sec: 90

llm_calls:
  token_estimation: tiktoken     # tiktoken | approximate
  max_context_tokens: 32000      # 上下文窗口上限
  truncation_policy:             # 超限裁剪策略（runtime §2.6）
    priority:
      - shrink_rule_chunks       # 规则只保留 top-3
      - summarize_history        # 摘要历史
      - truncate_data            # 截断最不相关数据

structured_output:
  max_parse_retry: 2             # chat_structured 解析失败重试次数

prompt_registry:
  prompts_dir: ./prompts         # Prompt 模板目录
  default_version: latest        # latest | 具体版本号

---

5. rag.yaml（RAG 层）

对应 docs/rag-layer-design.md §2 / §6 / §9：

# config/rag.yaml
embedding:
  model: BAAI/bge-small-zh-v1.5   # 可切 BAAI/bge-m3
  device: cpu                     # cpu | cuda
  max_batch_size: 32              # 编码批大小
  cache_dir: /data/shared/models  # 模型缓存目录

vector_store:                     # StorageAdapter 配置（rag-layer §9.4）
  adapter: chroma                 # chroma | qdrant
  chroma:
    persist_dir: /data/shared/rules-handbook/chroma
  qdrant:
    url: http://qdrant:6333
    api_key: ${QDRANT_API_KEY}    # 可选

chunking:
  word_max_tokens: 512            # Word chunk 上限
  excel_rule_block_rows: 10       # Excel 规则块最大行数
  ppt_pages_per_chunk: 2          # PPT 每 chunk 页数
  min_tokens: 30                  # 过短合并阈值

retrieval:
  channel_top_k: 10               # 双通道各取 top-10
  rrf_k: 60                       # RRF 融合常数（rag-layer §6.2）
  default_top_k: 5                # 融合后默认返回数
  contextual_enrichment: true     # 上下文增强开关（§6.3）

---

6. Docker Compose 草案

6.1 最小（开发/演示，InMemoryQueue）

# docker-compose.yml
services:
  api:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    volumes:
      - ./data:/data
      - ./config:/config
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000

6.2 完整（生产，队列 + 可选 Qdrant）

# docker-compose.yml
services:
  api:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    volumes:
      - ./data:/data
      - ./config:/config
    depends_on:
      - queue
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000

  worker:
    build: .
    env_file: .env
    volumes:
      - ./data:/data
      - ./config:/config
    depends_on:
      - queue
    command: python -m app.worker

  queue:
    image: valkey/valkey:8        # 零许可风险；或 redis:7（内部使用合法）
    volumes:
      - queue_data:/data

  # 可选：切换 Qdrant 时启用
  # qdrant:
  #   image: qdrant/qdrant
  #   ports: ["6333:6333"]
  #   volumes:
  #     - qdrant_data:/qdrant/storage

volumes:
  queue_data:
  # qdrant_data:

---

7. 配置校验与脱敏

• 校验：启动时 pydantic 模型校验全部 YAML 与环境变量；非法值直接报错并列出原因，不静默兜底（敏感项除外）
• 脱敏：GET /api/settings（api-design §2.8）返回配置前，过滤所有含 key/secret/token 字段，以 *** 替代
• 缺失 Key 行为：主模型 Key 缺失 → 启动成功但 LLM 相关 API 返回 503 LLM_NOT_CONFIGURED；备用模型 Key 缺失 → 降级日志警告，不使用 fallback