256 lines
7.4 KiB
Markdown
256 lines
7.4 KiB
Markdown
# 统一配置设计
|
||
|
||
> 版本: 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
|