env.example

# ============================================================
# RAG API 配置文件
# ============================================================
# 使用说明：
# 1. 复制此文件为 .env：cp env.example .env
# 2. 填入真实的 API 密钥
# 3. 根据需要调整可选配置
# ============================================================

# ====== LLM 配置 ======
# 用于文本生成、实体提取、关系提取等
LLM_API_KEY="your_llm_api_key_here"
LLM_BASE_URL="https://ark.ap-southeast.bytepluses.com/api/v3"
# 使用的模型名称
LLM_MODEL=seed-1-6-250615
# 用于多模态图片理解的 VLM 模型（必填，独立于 LLM_MODEL）
VLM_MODEL=seed-1-6-250615
# 可选：VLM 使用独立的密钥/域名（未设置时复用 LLM 配置）
# VLM_API_KEY="your_vlm_api_key_here"
# VLM_BASE_URL="https://api.example.com/v1"
# LLM 供应商标识（ark/openai/claude）
LLM_PROVIDER=ark
# VLM 图片理解 API 超时时间（秒，默认 120 秒）
LLM_VLM_TIMEOUT=120

# --- LLM 速率限制配置 ---
# 根据硅基流动 L0 等级（RPM=1000, TPM=50000）的 80% 保守设置
# 用于避免触发 429 错误（TPM limit reached）
LLM_REQUESTS_PER_MINUTE=800        # 每分钟最大请求数（默认 800）
LLM_TOKENS_PER_MINUTE=40000        # 每分钟最大令牌数（包含输入+输出，默认 40000）

# LLM_MAX_ASYNC=8                  # 【可选，专家模式】全局并发数
#                                  # 未设置时，系统会自动计算：min(RPM, TPM / 3500)
#                                  # 推荐：不设置此项，让系统自动计算以确保不超过 TPM/RPM 限制
#                                  # 计算示例：min(800, 40000/3500) = min(800, 11) = 11 并发

# ====== Embedding 配置 ======
# 用于向量化文本，支持语义检索
EMBEDDING_BASE_URL="https://api.siliconflow.cn/v1"
EMBEDDING_API_KEY="your_embedding_api_key_here"
# 使用的 Embedding 模型
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
# Embedding 向量维度（必须与模型输出维度严格匹配！）
# ⚠️ 重要：修改模型后必须同步修改此值，否则服务会失败
# 常见模型维度：
#   Qwen/Qwen3-Embedding-0.6B → 1024 维
#   Qwen/Qwen3-Embedding-8B   → 1024 维
#   text-embedding-3-small    → 1536 维
#   BAAI/bge-large-zh-v1.5    → 1024 维
EMBEDDING_DIM=1024
# Embedding 供应商标识（siliconflow/openai）
EMBEDDING_PROVIDER=siliconflow

# --- Embedding 速率限制配置 ---
# 根据硅基流动 L0 等级（RPM=2000, TPM=500000）的 80% 保守设置
EMBEDDING_REQUESTS_PER_MINUTE=1600  # 每分钟最大请求数（默认 1600）
EMBEDDING_TOKENS_PER_MINUTE=400000  # 每分钟最大令牌数（默认 400000）

# EMBEDDING_MAX_ASYNC=32            # 【可选，专家模式】全局并发数
#                                   # 未设置时，系统会自动计算：min(RPM, TPM / 500)
#                                   # 推荐：不设置此项，让系统自动计算
#                                   # 计算示例：min(1600, 400000/500) = min(1600, 800) = 800 并发
EMBEDDING_TIMEOUT=30                # HTTP 请求超时（秒，默认 30）

# ====== Rerank 配置（重排序模型） ======
# 用于提升检索结果的相关性（可选但推荐）
RERANK_API_KEY="your_rerank_api_key_here"
RERANK_BASE_URL="https://api.siliconflow.cn/v1"
# 使用的 Rerank 模型
RERANK_MODEL=Qwen/Qwen3-Reranker-8B
# Rerank 供应商标识（siliconflow/openai）
RERANK_PROVIDER=siliconflow
# 注意：如果 Rerank 和 Embedding 使用同一账号，API Key 可以填写相同值

# --- Rerank 速率限制配置 ---
# 根据硅基流动 L0 等级（RPM=2000, TPM=500000）的 80% 保守设置
RERANK_REQUESTS_PER_MINUTE=1600    # 每分钟最大请求数（默认 1600）
RERANK_TOKENS_PER_MINUTE=400000    # 每分钟最大令牌数（默认 400000）

# RERANK_MAX_ASYNC=16              # 【可选，专家模式】全局并发数
#                                  # 未设置时，系统会自动计算：min(RPM, TPM / 500)
#                                  # 推荐：不设置此项，让系统自动计算
#                                  # 计算示例：min(1600, 400000/500) = min(1600, 800) = 800 并发
RERANK_TIMEOUT=30                  # HTTP 请求超时（秒，默认 30）

# ====== MinerU 配置 ======

# --- MinerU 运行模式 ---
# 选项：
#   local  - 本地运行 MinerU（需要 GPU、大内存）
#   remote - 使用远程 MinerU API（推荐，节省资源）
MINERU_MODE=remote

# --- 远程 MinerU API 配置 ---
# 官方文档：https://mineru.net/apiManage/docs
# 注册地址：https://mineru.net（免费账号每天 2000 页额度）
# 优势：无需 GPU、无需下载模型、降低本地资源消耗
# 注意：只需要一个 Token（在官网申请）
MINERU_API_TOKEN=your_mineru_api_token_here
MINERU_API_BASE_URL=https://mineru.net
MINERU_MODEL_VERSION=vlm

# --- 文件服务 URL（用于 MinerU 远程模式） ---
# 本地测试：http://localhost:8000
# 生产环境：https://download.myvibe.works
FILE_SERVICE_BASE_URL=http://localhost:8000

# --- 远程 MinerU 限流配置 ---
# 根据您的 API 套餐调整
MINERU_MAX_CONCURRENT_REQUESTS=5     # 最大并发请求数
MINERU_REQUESTS_PER_MINUTE=60        # 每分钟最大请求数
MINERU_RETRY_MAX_ATTEMPTS=3          # 失败重试次数
MINERU_POLL_TIMEOUT=600              # 任务轮询超时（秒）
MINERU_HTTP_TIMEOUT=60               # HTTP 请求超时（秒，默认 60）

# ====== DeepSeek-OCR 配置（v2.0 智能 Parser 选择方案） ======
# 基于 4 类真实场景完整测试（IELTS + Visa + Statement + 毕业证）
# 性能：5.18-10.95s，成本节省 70-90%，可替代 80% MinerU 场景

# --- 基础配置（独立 API Key，不复用 Embedding） ---
DS_OCR_API_KEY="your_deepseek_ocr_api_key_here"
DS_OCR_BASE_URL="https://api.siliconflow.cn/v1"
DS_OCR_MODEL="deepseek-ai/DeepSeek-OCR"

# --- OCR 模式配置 ---
# free_ocr: 纯 Markdown 输出（最快，80% 场景）
# grounding: HTML + bbox（复杂表格 15%）
# ocr_image: 词级 bbox（不稳定，不推荐）
DEEPSEEK_OCR_DEFAULT_MODE=free_ocr

# --- 智能降级配置 ---
# 启用智能降级：Free OCR 输出 <500 字符时自动降级 Grounding
DEEPSEEK_OCR_FALLBACK_ENABLED=true
DEEPSEEK_OCR_FALLBACK_MODE=grounding
DEEPSEEK_OCR_MIN_OUTPUT_THRESHOLD=500

# --- 性能配置 ---
DEEPSEEK_OCR_TIMEOUT=60        # API 请求超时（秒）
DEEPSEEK_OCR_MAX_TOKENS=4000   # 最大输出 tokens
DEEPSEEK_OCR_DPI=200           # PDF 转图片 DPI（150=可能幻觉，200=稳定，300=慢）

# --- DeepSeek-OCR 速率限制配置 ---
# DeepSeek-OCR 是 LLM 类型 API，使用与 LLM 相同的限制规则
DS_OCR_REQUESTS_PER_MINUTE=800     # 每分钟最大请求数（默认 800）
DS_OCR_TOKENS_PER_MINUTE=40000     # 每分钟最大令牌数（默认 40000）
# DS_OCR_MAX_ASYNC=8               # 【可选】全局默认并发数（未设置时使用硬编码默认值 8）

# ====== 智能 Parser 选择器配置（v2.0） ======
# 基于文档复杂度自动选择最优 Parser 和模式

# --- Parser 模式 ---
# auto: 智能选择（推荐，基于复杂度分析）
# deepseek-ocr: 强制使用 DeepSeek-OCR
# mineru: 强制使用 MinerU
# docling: 强制使用 Docling
PARSER_MODE=auto

# --- 复杂度评分阈值 ---
COMPLEXITY_SIMPLE_THRESHOLD=20                  # < 20：简单文档 → Free OCR
COMPLEXITY_MEDIUM_TABLE_THRESHOLD=40            # 20-40：中等表格 → Grounding
COMPLEXITY_COMPLEX_SINGLE_PAGE_THRESHOLD=60     # 40-60：复杂单页 → 检查中文密度
                                                # ≥ 60：极复杂多模态 → MinerU

# --- 特殊规则阈值 ---
COMPLEXITY_SIMPLE_TABLE_ROW_LIMIT=10            # 简单表格行数上限（< 10 行 → Free OCR）
COMPLEXITY_COMPLEX_TABLE_ROW_LIMIT=20           # 复杂表格行数下限（≥ 20 行 → Grounding）
COMPLEXITY_CHINESE_CHAR_LOW_THRESHOLD=10        # 中文字符少（< 10 → 添加语言提示）
COMPLEXITY_CHINESE_CHAR_HIGH_THRESHOLD=0.3      # 中文密度高（> 30% → Free OCR）

# --- 选择偏好 ---
COMPLEXITY_PREFER_SPEED=true   # 是否优先速度（true/false）

# ====== 系统配置 ======

# --- 日志配置 ---
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

# --- 文件上传限制 ---
MAX_UPLOAD_SIZE=104857600  # 100MB (字节)

# --- 工作目录 ---
WORKING_DIR=./rag_local_storage

# --- 文档处理并发控制 ---
# 限制同时处理的文档数量，防止 OOM

# --- 文档插入验证配置 ---
# 基于 track_id 验证文档是否真正插入到 LightRAG
# 原理：通过 ainsert() 返回的 track_id 查询文档状态，如果 doc_id 不在结果中说明被去重
DOC_INSERT_VERIFICATION_TIMEOUT=300        # 验证超时时间（秒），默认 5 分钟
DOC_INSERT_VERIFICATION_POLL_INTERVAL=0.5  # 轮询间隔（秒），默认 500ms

# --- 模型调用超时配置 ---
# 用于控制 LLM/Embedding/Rerank 模型调用的 Future 超时
# 超时包含：RateLimiter 等待时间 + API 调用时间 + 缓冲时间
MODEL_CALL_TIMEOUT=90  # 模型调用最大超时（秒），默认 90 秒

# ====== LightRAG 查询优化参数 ======
# 用于控制查询性能和质量的平衡

# --- 检索参数 ---
# top_k: 检索的实体/关系数量（默认 60，推荐 20-40）
# 数值越大，检索越全面但速度越慢
TOP_K=20

# chunk_top_k: 检索的文本块数量（默认 20，推荐 10-20）
CHUNK_TOP_K=10

# --- Token 限制 ---
# 控制 LLM 调用时的上下文大小
MAX_ENTITY_TOKENS=6000      # 实体上下文最大 token 数
MAX_RELATION_TOKENS=8000    # 关系上下文最大 token 数
MAX_TOTAL_TOKENS=30000      # 总 token 数限制

# --- 并发配置 ---
# ⚠️ 所有 API 并发控制由 RateLimiter 统一管理（rate_limiter.py）
# 三层配置优先级：租户配置 > 环境变量 (*_MAX_ASYNC) > 硬编码默认值
# 硬编码默认值：LLM=8, Embedding=32, Rerank=16, DS_OCR=8
# 租户可通过租户配置 API 单独覆盖（/tenants/{id}/config）
MAX_PARALLEL_INSERT=2       # 文档插入最大并发数

# --- 元数据管理配置（v1.4.9.4 新增） ---
# 用于优化大规模知识图谱的性能
# 限制每个实体/关系的源文档ID数量，防止元数据膨胀
MAX_SOURCE_IDS_PER_ENTITY=300      # 每个实体最大源文档ID数（默认300）
MAX_SOURCE_IDS_PER_RELATION=300    # 每个关系最大源文档ID数（默认300）
SOURCE_IDS_LIMIT_METHOD=FIFO       # 限制策略：FIFO（先进先出）或 KEEP（保留现有）
MAX_FILE_PATHS=100                 # 最大文件路径数（默认100）

# ====== 多租户配置 ======

# --- 租户实例缓存配置 ---
# 最多缓存多少个租户实例（超过后会使用 LRU 策略清理）
MAX_TENANT_INSTANCES=50

# ====== RAG-Anything VLM 增强配置 ======
# 用于控制 MinerU 远程模式下的图表处理质量

# --- VLM 处理模式 ---
# 三种模式：
#   off       - 仅 Markdown（最快，默认）
#   selective - 混合模式（选择性处理重要图表，平衡性能和质量）
#   full      - 完整 RAG-Anything 处理（最高质量，启用上下文增强）
RAG_VLM_MODE=off

# --- selective 模式配置 ---
# 重要性阈值（0-1）：bbox 面积超过此值的图表会被处理
RAG_IMPORTANCE_THRESHOLD=0.5

# --- full 模式配置 ---
# 上下文窗口大小（页数）：前后各提取 N 页作为上下文
RAG_CONTEXT_WINDOW=2

# 上下文模式：page（按页）或 chunk（按块）
RAG_CONTEXT_MODE=page

# 最大上下文 tokens
RAG_MAX_CONTEXT_TOKENS=3000

# ====== LightRAG 响应增强配置 ======
# 控制 LLM 回答问题时的行为，防止在信息不足时编造答案

# --- 严格 Grounding 模式 ---
# 启用后，当知识库中没有足够信息回答问题时，AI 会明确拒绝回答
# 而不是强行编造答案
# 可选值: true, false
# 默认：注释掉或设置为 false（使用 LightRAG 原生行为）
# LIGHTRAG_STRICT_GROUNDING=true  # 取消注释以启用严格 Grounding

# --- 自定义 RAG 响应 Prompt（可选）---
# 完全自定义 RAG 响应 prompt，覆盖默认和增强版
# LIGHTRAG_RAG_RESPONSE_PROMPT="你的自定义 prompt..."
# LIGHTRAG_NAIVE_RAG_RESPONSE_PROMPT="你的自定义 naive 模式 prompt..."

# ====== 存储后端配置 ======
# LightRAG 存储层配置（必须与 docker-compose 中的服务匹配）

# --- Vector Storage ---
# 用于存储文档向量和语义检索
# 可选值: QdrantVectorDBStorage, MilvusVectorDBStorage, PGVectorStorage, etc.
VECTOR_STORAGE=QdrantVectorDBStorage

# --- Key-Value Storage ---
# 用于缓存和临时数据存储
# 可选值: RedisKVStorage, JsonKVStorage
KV_STORAGE=RedisKVStorage

# --- Graph Storage ---
# 用于存储知识图谱（实体和关系）
# 可选值: MemgraphStorage, Neo4JStorage
GRAPH_STORAGE=MemgraphStorage

# --- Document Status Storage ---
# 用于存储文档处理状态和追踪信息
# 推荐值: RedisDocStatusStorage（生产环境）, JsonDocStatusStorage（开发环境）
# 其他支持: MongoDocStatusStorage, PGDocStatusStorage
DOC_STATUS_STORAGE=RedisDocStatusStorage

# ====== 可选配置 ======

# --- 租户配置存储 ---
# 控制租户配置的存储方式：
#   local - 本地 JSON 文件存储（默认，适合开发/测试环境）
#   redis - Redis 存储（适合生产环境，需要 Redis 服务）
TENANT_CONFIG_STORAGE=local

# 本地存储目录（当 TENANT_CONFIG_STORAGE=local 时使用）
TENANT_CONFIG_DIR=./tenant_configs

# --- 任务存储配置 ---
# 控制任务状态的存储方式：
#   memory - 内存存储（默认，重启后数据丢失，适合开发环境）
#   redis  - Redis 存储（推荐生产环境，支持容器重启和实例重建后恢复）
# ⚠️ 重要：
#   - 多租户实例 LRU=50，超过会销毁重建，内存模式下任务会丢失
#   - Redis 模式自动设置 TTL（completed=24h, failed=24h, pending/processing=6h）
TASK_STORE_STORAGE=memory

# --- 时区 ---
TZ=Asia/Shanghai

# --- Python 配置 ---
PYTHONUNBUFFERED=1  # 禁用输出缓冲，实时查看日志