基于 LangChain + OpenAI 兼容 LLM + BGE 本地向量模型 + ChromaDB 构建的 Tongsuo 文档问答系统，支持 CLI 与 Gradio Web。

推荐 Python 版本：3.11.x（当前项目固定为 3.11.15）。

pyenv local 3.11.15

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

在 .env 中填写：

# 方案 A（推荐）：聊天与 embedding 分家
LLM_API_KEY=your_llm_key_here
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# 方案 A1：本地 embedding（推荐与 DeepSeek 搭配）
EMBED_PROVIDER=local
EMBED_LOCAL_MODEL=BAAI/bge-small-zh-v1.5

# 方案 A2：OpenAI 兼容 embedding（可选）
# EMBED_PROVIDER=openai
# EMBED_API_KEY=your_embed_key_here
# EMBED_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small  # 仅 openai provider 生效

# 方案 B（兼容回退）：仍可只填 OPENAI_*
# OPENAI_API_KEY=your_unified_key_here
# OPENAI_BASE_URL=https://api.openai.com/v1

注意：.env 必须是 KEY=VALUE 格式，不是 JSON/YAML，例如不要写成 "OPENAI_API_KEY": "..."。

将 markdown/pdf/txt/rst 文件放入：

data/raw/local/

python main.py ingest --local-only

完整摄入（含 GitHub + 官网）：

python main.py ingest

单轮问答：

python main.py ask "Tongsuo 如何启用 SM2 签名？"

多轮对话：

python main.py chat

启动 Web：

python main.py web

默认地址：http://127.0.0.1:7860

• config/settings.py 配置
• src/loaders/ 三类加载器（local/github/website）
• src/processing/ 分块与增量入库
• src/retrieval/ 检索封装
• src/chain/qa_chain.py RAG 问答链
• src/interface/ CLI 与 Web
• scripts/ingest.py 摄入逻辑

src/processing/embedder.py 会维护 data/.ingest_state.json：

• 若文档 doc_hash 未变化，跳过重复入库
• 若文档变化，先删旧向量再写新向量

• Embedding 请求失败 或 404 page not found： 当前 EMBED_BASE_URL（或兼容回退 OPENAI_BASE_URL）可能只支持聊天接口，不支持 /v1/embeddings。RAG 入库需要 embedding 接口，请更换为支持 embeddings 的服务端点，或改用 EMBED_PROVIDER=local。