# 统一配置设计

> 版本: 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 配置目录

# ── 队列（v1 仅 InMemory；Redis/Valkey 为 v2 预留，Scope 缩减裁定）──
QUEUE_BACKEND=memory                 # v1 仅 memory
```

| 变量 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `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              # v1 仅 memory（redis/valkey 为 v2 预留）
  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（内置估算器，T9 起对 CJK 保守 ×1.5/字符）
  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-m3                 # 多语言（中/日/英），适配日文语料（OV2/T11）
  device: cpu                        # cpu | cuda
  max_batch_size: 32                 # 编码批大小
  cache_dir: /data/shared/models     # 模型缓存目录

vector_store:                     # StorageAdapter 配置（rag-layer §9.4）
  adapter: chroma                 # v1 仅 chroma（qdrant 为 v2 预留）
  chroma:
    persist_dir: /data/shared/rules-handbook/chroma

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.4）

rerank:                           # Rerank 精排（rag-layer §6.3，v1 新增 I6/T6）
  enabled: true                   # false 时跳过精排，直接取 RRF 前 top_k
  model: BAAI/bge-reranker-v2-m3  # 多语言 Cross-Encoder
  device: cpu                     # cpu | cuda
```

---

## 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 生产（v1 单容器；worker/queue 为 v2 预留）

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

  # worker / queue（valkey）: v2 预留（Scope 缩减裁定移除 Redis/Valkey 双实现）
  # qdrant: v2 预留（Qdrant 切换已移除）
```

---

## 7. 配置校验与脱敏

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