chore: 基线提交——既有设计文档与样本数据
This commit is contained in:
@@ -0,0 +1,255 @@
|
||||
# 统一配置设计
|
||||
|
||||
> 版本: 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
|
||||
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
|
||||
Reference in New Issue
Block a user