# ChatDoc

**Repository Path**: lxj-creator/chat-doc

## Basic Information

- **Project Name**: ChatDoc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatDoc 智能文档助手

零成本 RAG 学习项目：**本地 embedding + 本地向量库 + 免费 LLM**。
只有最终「生成回答」一步走网络（智谱 glm-4-flash，免费），其余全在你机器上。

## 架构

```
data/documents/ (txt / md / pdf / docx)
      │
      ▼  services/document_loader.py   加载 + 中文友好切分（500字/块，重叠80）
      ▼  services/embeddings.py        本地推理 bge-small-zh-v1.5（models/bge-small-zh）
      ▼  services/vectorstore.py       Chroma 嵌入式向量库（data/chroma 落盘）
      ▼  services/rag.py               检索 Top-4 → 组装 Prompt → GLM-4-Flash 生成
      ▼
   api/routes.py (FastAPI)  或  cli.py (命令行)
```

## 项目结构

```
ChatDoc/
├── src/chatdoc/
│   ├── main.py                  # FastAPI 入口（python main.py 可直接启动）
│   ├── cli.py                   # 命令行问答入口
│   ├── config.py                # pydantic-settings 配置
│   ├── schemas.py               # API 请求/响应模型
│   ├── api/routes.py            # /api/v1 路由
│   ├── services/
│   │   ├── embeddings.py        # 本地 embedding（单例，bge-zh 自动加检索指令）
│   │   ├── document_loader.py   # 加载 + 切分
│   │   ├── ingestion.py         # 入库管道（含按文件去重）
│   │   ├── vectorstore.py       # Chroma 封装
│   │   └── rag.py               # RAG 问答链
│   └── utils/logger.py
├── models/bge-small-zh/         # 已下载的 embedding 模型（普通目录，离线可用）
├── tests/                       # 切分逻辑单测（无网络依赖）
├── data/
│   ├── documents/               # 放你的文档
│   └── chroma/                  # 向量库落盘（自动生成）
├── pyproject.toml
└── .env.example
```

## 快速开始

```bash
# 1. 创建虚拟环境并安装依赖（国内走清华镜像）
.venv\Scripts\python -m venv .venv          # 没有 .venv 时先建
.venv\Scripts\pip install -e ".[dev]" --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 配置密钥：去 https://open.bigmodel.cn 申请（免费）
copy .env.example .env
# 编辑 .env，填 LLM_API_KEY

# 3. 放几个文档到 data/documents/（txt/md/pdf/docx）

# 4. 跑测试（不需要网络和密钥）
.venv\Scripts\python -m pytest

# 5. 方式一：命令行问答
.venv\Scripts\python -m chatdoc.cli
#   > ingest     （使用本地模型，无需下载）
#   > LangChain 的 TextSplitter 有哪些参数？

# 5. 方式二：API 服务
.venv\Scripts\python -m uvicorn chatdoc.main:app --reload
#   Swagger 文档: http://127.0.0.1:8000/docs
```

## API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/ingest` | 入库文档，body: `{"directory": null, "force": false}` |
| POST | `/api/v1/ask` | RAG 问答，body: `{"question": "..."}` |
| GET  | `/api/v1/documents` | 已入库文档列表 |
| DELETE | `/api/v1/documents/{source}` | 按文件名删除向量 |
| GET  | `/api/v1/config` | 当前生效配置（脱敏） |
| GET  | `/health` | 健康检查 |

## 换供应商（不改代码）

编辑 `.env` 三个变量即可，全部兼容 OpenAI 协议：

| 供应商 | LLM_BASE_URL | LLM_MODEL |
|--------|-------------|-----------|
| 智谱（免费） | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |
| DeepSeek（极便宜） | `https://api.deepseek.com/v1` | `deepseek-chat` |
| 硅基流动 | `https://api.siliconflow.cn/v1` | `Qwen/Qwen2.5-72B-Instruct` |

## 换 embedding 模型

默认用项目内已下载的 `models/bge-small-zh`（约 190MB，中文效果好的小模型，纯离线）。
想换模型时：在 `.env` 里取消注释 `EMBEDDING_MODEL` 并填模型 id（如 `BAAI/bge-m3`），
重启后自动从 `HF_ENDPOINT` 镜像下载；国内直连 HuggingFace 会超时，务必保留镜像配置。

## 调优建议

- **检索不准** → 调 `.env` 的 `CHUNK_SIZE`（300–800 之间试）和 `RETRIEVER_K`（4–8）；
- **回答太啰嗦/太干** → 改 `services/rag.py` 里的 `PROMPT_TEMPLATE`；
- **有 NVIDIA 显卡** → `.env` 里 `EMBEDDING_DEVICE=cuda`，向量化快一个数量级；
- **想要 rerank 提精度** → 加 `langchain-cross-encoders`，在 `rag.py` 里 retriever 后接重排序。

## 常见坑

1. **`/ask` 报 400**：向量库为空，先 `POST /api/v1/ingest`。
2. **txt 乱码**：加载器已开 `autodetect_encoding`，仍乱码就用记事本另存为 UTF-8。
3. **改了文档内容没生效**：入库按文件名去重，先 `DELETE /api/v1/documents/文件名` 再重新 ingest。
4. **`langchain-community` 弃用警告**：LangChain 1.x 中 PDF/DOCX 加载器仍托管在 `langchain-community`（官方正在拆分到独立包），警告可忽略。