ChatPDF：本地文档智能交互解决方案

1. 核心价值解析：重新定义文档交互体验

在信息爆炸的时代，如何高效处理和提取PDF、TXT等文档中的关键信息成为知识工作者的重要挑战。ChatPDF项目基于检索增强生成（RAG，Retrieval-Augmented Generation）技术，实现了本地大语言模型（LLM）与文档内容的深度交互。这一解决方案的核心价值体现在三个维度：

数据隐私保护 ⚙️
所有文档处理和模型推理均在本地完成，避免敏感信息上传至云端，特别适合处理医疗报告、法律文件等隐私性要求高的场景。项目中data/目录专门用于存储本地知识库，如medical_corpus.jsonl和三国演义.txt等示例文件，确保数据全程可控。

知识增强能力
通过将文档内容转化为向量嵌入（Embedding）并构建本地向量库，ChatPDF能精准定位与用户问题相关的文本片段，使LLM回答既有生成能力又有事实依据。这种架构解决了传统大模型"幻觉"问题，特别适合专业领域的深度问答。

多格式兼容与轻量化部署
支持PDF、TXT等主流文档格式，通过graphrag/模块实现高效的知识图谱构建，同时兼容Ollama等本地LLM运行时，最低仅需8GB内存即可部署使用，满足个人开发者和中小企业的资源需求。

图1：ChatPDF的RAG技术架构示意图，展示从文档解析到智能问答的完整流程

2. 零基础环境部署：3步完成依赖配置

2.1 项目获取与环境准备

首先通过Git工具克隆项目代码库到本地：

git clone https://gitcode.com/gh_mirrors/cha/ChatPDF
cd ChatPDF

小贴士：如果您的网络环境有限制，可以通过配置Git代理加速克隆过程：
git config --global http.proxy http://proxy.example.com:port

2.2 Python依赖安装

项目依赖项已在requirements.txt中详细列出，推荐使用Python 3.8-3.10版本。执行以下命令安装依赖：

# 创建虚拟环境（可选但推荐）
python -m venv venv
source venv/bin/activate  # Linux/MacOS
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

⚠️ 注意事项：部分依赖如torch和transformers可能需要根据您的硬件配置选择CPU/GPU版本，建议参考官方文档调整安装命令。

2.3 模型准备

ChatPDF支持多种本地LLM，推荐使用Ollama进行模型管理：

1. 安装Ollama（参考官方文档）
2. 拉取适合的模型：

ollama pull mistral  # 轻量级模型（约4GB）
# 或
ollama pull llama2:7b  # 平衡性能与资源的选择

硬件要求参考：

• 7B参数模型：最低8GB内存，推荐16GB
• 13B参数模型：最低16GB内存，推荐32GB并启用GPU加速

3. 功能解析：核心模块与技术路径

3.1 核心执行流程

ChatPDF的主程序入口位于项目根目录，提供多种运行模式：

• Web界面模式：通过webui.py启动交互式网页界面，适合非技术用户
• 命令行模式：rag.py提供基础RAG功能，graphrag_demo.py展示知识图谱增强能力
• 批量处理模式：batch_rag_demo.py支持多文档批量问答任务

典型执行流程如下：

1. 文档加载（支持data/目录下的PDF/TXT文件）
2. 文本提取与分块（默认chunk size为500字符）
3. 向量嵌入生成（使用graphrag/nano_vectordb.py实现本地存储）
4. 用户查询处理与相似性检索
5. LLM生成回答（支持Ollama或API调用模式）

3.2 关键参数决策指南

项目配置通过代码内参数控制，核心配置项如下表：

参数类别	关键参数	推荐值	适用场景
文档处理	chunk_size	500-1000	技术文档选大值，文学类选小值
向量存储	top_k	3-5	问题复杂时增大，简单问答减小
LLM配置	temperature	0.3-0.7	事实性问答选0.3，创意生成选0.7
界面设置	port	7860	默认端口，冲突时修改为8080等

如需自定义配置，可直接修改对应Python文件中的参数定义，例如webui.py中的端口设置：

# /data/web/disk1/git_repo/gh_mirrors/cha/ChatPDF/webui.py
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--port", type=int, default=7860, help="Server port")
    # ...其他参数

3.3 知识图谱增强功能

graphrag/目录实现了基于知识图谱的高级检索能力，通过实体识别和关系抽取构建文档的语义网络。核心文件包括：

• graphrag.py：知识图谱构建主逻辑
• _model.py：实体与关系提取模型
• _storage.py：图谱数据持久化

这一功能特别适合处理结构化知识密集型文档，如医疗指南、法律条文等，能显著提升复杂问题的回答准确性。

4. 实践操作：从文档上传到智能问答

4.1 启动Web界面

在项目根目录执行以下命令启动WebUI：

python webui.py

成功启动后，浏览器访问http://localhost:7860即可看到交互界面。界面主要包含三个区域：文档上传区、对话区和历史记录区。

图2：ChatPDF WebUI交互界面，支持多轮对话和文档管理

4.2 文档处理步骤

1. 上传文档：点击界面上方"Upload Document"按钮，选择本地PDF或TXT文件（推荐单个文件不超过100MB）
2. 等待处理：系统会自动进行文本提取和向量构建，大型文档可能需要1-3分钟
3. 开始问答：在输入框中键入问题，例如"总结本文的核心观点"或"解释第三章提到的技术原理"

小贴士：对于超过200页的大型文档，建议先分割为多个小文件，可提高处理速度和问答准确性。

4.3 高级功能使用

批量处理：

python batch_rag_demo.py --input_dir ./data --output_file results.json

知识图谱模式：

python graphrag_ollama_demo.py --doc_path ./data/sample.pdf --model mistral

5. 常见问题速查

Q: 上传PDF后提示"无法提取文本"怎么办？

A: 这通常是由于PDF包含扫描图片而非文本内容。解决方案：

1. 使用OCR工具将图片PDF转换为文本PDF
2. 尝试项目中的data/三国演义.txt纯文本示例文件进行测试

Q: 回答速度很慢如何优化？

A: 可从三方面优化：

1. 降低模型参数规模（如从13B切换到7B模型）
2. 增大chunk_size减少检索次数
3. 确保Ollama启用GPU加速（通过ollama list检查模型运行设备）

Q: 如何添加自定义知识库？

A: 将文档放入data/目录，支持以下格式：

• PDF：支持多页文档和复杂排版
• TXT：纯文本文件，建议UTF-8编码
• JSONL：每行一个JSON对象的语料库格式（如medical_corpus.jsonl）

Q: 能否在无网络环境下使用？

A: 完全可以。确保：

1. 已提前下载Ollama模型
2. 所有依赖包已安装
3. 文档已放置在本地data/目录

6. 总结与扩展

ChatPDF通过将RAG技术与本地LLM结合，为用户提供了安全、高效的文档智能交互方案。无论是学术研究、专业学习还是企业文档管理，都能显著提升信息获取效率。项目后续将支持DOCX格式和多语言处理，欢迎通过项目Issue提交功能建议或贡献代码。

通过本文档的指导，您已掌握ChatPDF的核心功能和使用方法。如需深入了解技术细节，可参考graphrag/目录下的源代码实现，或研究batch_rag_demo.py中的批量处理逻辑。