# 统一配置设计

> 版本: v1.0 | 日期: 2026-07-30 | 状态: 初版
>
> 本文档统一定义本项目的全部配置项：`config/inference.yaml`、`config/rag.yaml`、`config/app.yaml`、`.env` 环境变量及 Docker Compose 草案。所有配置项**一处定义、一处生效**，避免散落。

---

## 目录

1. [配置层次与加载顺序](#1-配置层次与加载顺序)
2. [环境变量（.env）](#2-环境变量env)
3. [app.yaml（应用级）](#3-appyaml应用级)
4. [inference.yaml（推理引擎）](#4-inferenceyaml推理引擎)
5. [rag.yaml（RAG 层）](#5-ragyamlrag-层)
6. [Docker Compose 草案](#6-docker-compose-草案)
7. [配置校验与脱敏](#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）

```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（应用级）

```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 相关配置集中于此：

```yaml
# 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；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：

```yaml
# 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）

```yaml
# 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）

```yaml
# 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