PDF-Assistant-RAG AI技能包
AI Skill Hub 强烈推荐：PDF-Assistant-RAG AI技能包 是一款优质的AI工具。AI 综合评分 8.0 分，在同类工具中表现稳健。如果你正在寻找可靠的AI工具解决方案，这是一个值得深入了解的选择。
📚 深度解析
**为什么要使用开源工具而非商业 SaaS？**
对于个人开发者和有隐私需求的用户，本地部署的开源工具意味着数据不离本机，不受第三方服务商的数据政策约束。同时，开源工具通常没有使用次数限制和月度费用，一次安装即可长期使用，对于高频使用场景的总拥有成本（TCO）远低于订阅制商业工具。
**安装与环境准备**
PDF-Assistant-RAG AI技能包 依赖 TypeScript 运行环境。建议通过 pyenv（Python）或 nvm（Node.js）管理 TypeScript 版本，避免全局环境污染。对于新手用户，推荐先创建虚拟环境（python -m venv venv && source venv/bin/activate），再安装依赖，这样即使出现问题也可以随时删除虚拟环境重新开始，不影响系统稳定性。
**社区与维护**
GitHub Issue 和 Discussion 是获取帮助的最快渠道。在提问前建议先检查 Closed Issues（已关闭的问题），大多数常见问题都已有解答。遇到 Bug 时，提供 pip list 的输出、完整错误堆栈和最小可复现示例，能显著提高开发者响应速度。AI Skill Hub 将持续追踪 PDF-Assistant-RAG AI技能包 的版本更新，及时通知重要功能变化。
📋 工具概览
PDF-Assistant-RAG AI技能包 是一款基于 TypeScript 开发的开源工具，专注于 pdf、typescript、fastapi 等核心功能。作为 GitHub 开源项目，它拥有活跃的社区支持和持续的版本迭代，代码完全透明可审计，支持本地部署以保护数据隐私。无论是个人使用还是集成到企业工作流，都能提供稳定可靠的解决方案。
📖 中文文档
PDF-Assistant-RAG AI技能包 是一款基于 TypeScript 开发的开源工具，专注于 pdf、typescript、fastapi 等核心功能。作为 GitHub 开源项目，它拥有活跃的社区支持和持续的版本迭代，代码完全透明可审计，支持本地部署以保护数据隐私。无论是个人使用还是集成到企业工作流，都能提供稳定可靠的解决方案。
- 开源免费，支持本地部署，数据完全自主可控
- 活跃的 GitHub 开源社区，持续迭代更新
- 提供详细文档和使用示例，新手友好
- 支持自定义配置，灵活适配不同使用环境
- 可作为基础组件集成进现有技术栈或进行二次开发
- 本地部署运行，保护数据隐私，满足合规要求
- 自定义集成到现有系统，扩展技术栈能力
- 作为开源基础组件进行商业化二次开发
# 方式一：npm 全局安装 npm install -g pdf-assistant-rag # 方式二：npx 直接运行（无需安装） npx pdf-assistant-rag --help # 方式三：项目依赖安装 npm install pdf-assistant-rag # 方式四：从源码运行 git clone https://github.com/param20h/PDF-Assistant-RAG cd PDF-Assistant-RAG npm install npm start
- 访问 GitHub 仓库页面
- 按照 README 文档完成依赖安装
- 根据系统环境完成初始化配置
- 参考官方示例或文档开始使用
- 遇到问题可在 GitHub Issues 中查找解答
# 命令行使用
pdf-assistant-rag --help
# 基本用法
pdf-assistant-rag [options] <input>
# Node.js 代码中使用
const pdf_assistant_rag = require('pdf-assistant-rag');
const result = await pdf_assistant_rag.run(options);
console.log(result);
# pdf-assistant-rag 配置说明 # 查看配置选项 pdf-assistant-rag --config-example > config.yml # 常见配置项 # output_dir: ./output # log_level: info # workers: 4 # 环境变量（覆盖配置文件） export PDF_ASSISTANT_RAG_CONFIG="/path/to/config.yml"
简介
--- title: Document AI Analyst emoji: 🧠 colorFrom: indigo colorTo: purple sdk: docker app_port: 7860 pinned: true license: mit
short_description: Enterprise Agentic RAG — upload PDFs and chat with AI
<br/>
██████╗ ██████╗ ███████╗ █████╗ ███████╗███████╗██╗███████╗████████╗ █████╗ ███╗ ██╗████████╗
██╔══██╗██╔══██╗██╔════╝ ██╔══██╗██╔════╝██╔════╝██║██╔════╝╚══██╔══╝██╔══██╗████╗ ██║╚══██╔══╝
██████╔╝██║ ██║█████╗ ███████║███████╗███████╗██║███████╗ ██║ ███████║██╔██╗ ██║ ██║
██╔═══╝ ██║ ██║██╔══╝ ██╔══██║╚════██║╚════██║██║╚════██║ ██║ ██╔══██║██║╚██╗██║ ██║
██║ ██████╔╝██║ ██║ ██║███████║███████║██║███████║ ██║ ██║ ██║██║ ╚████║ ██║
╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚══════╝╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═╝
██████╗ █████╗ ██████╗
██╔══██╗██╔══██╗██╔════╝
██████╔╝███████║██║ ███╗
██╔══██╗██╔══██║██║ ██║
██║ ██║██║ ██║╚██████╔╝
╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝🌟 Overview
PDF-Assistant-RAG is a complete, production-ready AI document assistant that lets users upload complex PDFs, financial reports, legal contracts, and research papers — then chat with an AI that provides accurate, cited answers powered by a multi-stage Retrieval-Augmented Generation pipeline.
The system uses hybrid search (vector + BM25) with Reciprocal Rank Fusion and cross-encoder reranking to find the most relevant document chunks, streams AI-generated answers token-by-token, and highlights exact source citations with page numbers — all inside a modern Next.js frontend with JWT-secured per-user data isolation.
<br/>
🔄 System Flow Overview
- User uploads a document via the Next.js frontend.
- FastAPI queues a Celery ingestion task backed by Redis.
- The worker chunks the document, generates local embeddings (cached via Redis/LRU), builds a BM25 index, and stores vectors in ChromaDB.
- At query time, hybrid search merges vector and BM25 results via Reciprocal Rank Fusion.
- A cross-encoder reranker refines the top candidates.
- The agent assembles a prompt and calls the HuggingFace Inference API.
- Streamed SSE tokens are returned to the frontend chat panel.
<br/>
✨ Key Features
Prerequisites
Python 3.11+
Node.js 20+
Docker + Docker Compose (recommended)
HuggingFace API token — huggingface.co/settings/tokens (free)
---
GPU-accelerated (requires NVIDIA Container Toolkit)
docker compose --profile gpu up --build
🚀 Getting Started
3. Run with Docker (recommended)
```bash
4. Run Locally (without Docker)
```bash
Docker
| Command | Description |
|---|---|
docker compose --profile cpu up --build | Full stack — CPU only |
docker compose --profile gpu up --build | Full stack — GPU accelerated |
docker compose --profile debug up | Also start pgAdmin at http://localhost:5050 |
docker compose down | Stop all containers |
GPU profile requires NVIDIA Container Toolkit.
<br/>
🌐 Deployment
2. Configure Environment
cp .env.example .envEdit .env:
SECRET_KEY=your-strong-random-secret
DATABASE_URL=postgresql://pdf_rag_user:pdf_rag_pass@localhost:5432/pdf_rag
HF_TOKEN=hf_your_huggingface_token_here
UPLOAD_DIR=./data/uploads
CHROMA_PERSIST_DIR=./data/chroma_db
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1Get your free HuggingFace token at huggingface.co/settings/tokens
Email Verification Setup (optional)
FRONTEND_URL=http://localhost:3000
MAIL_USERNAME=your_smtp_username
MAIL_PASSWORD=your_smtp_or_gmail_app_password
MAIL_FROM=your_sender_email@example.com
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_STARTTLS=True
MAIL_SSL_TLS=FalseWithout SMTP settings, registration returns a local verification link so contributors can test without email credentials.
5. Set up crawl4ai (URL Upload Feature — optional)
crawl4ai-setup<br/>
📦 Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
SECRET_KEY | ✅ | — | JWT signing secret. Generate: python -c "import secrets; print(secrets.token_urlsafe(32))" |
HF_TOKEN | ✅ | — | HuggingFace API token for LLM inference |
DATABASE_URL | ❌ | sqlite:///./data/app.db | SQLAlchemy connection string (SQLite or PostgreSQL) |
CELERY_BROKER_URL | ❌ | redis://localhost:6379/0 | Redis broker for Celery |
CELERY_RESULT_BACKEND | ❌ | redis://localhost:6379/1 | Redis backend for Celery results |
REDIS_URL | ❌ | — | Redis URL for response + embedding cache |
UPLOAD_DIR | ❌ | ./data/uploads | File storage directory |
CHROMA_PERSIST_DIR | ❌ | ./data/chroma_db | ChromaDB persistence directory |
EMBEDDING_MODEL | ❌ | sentence-transformers/all-MiniLM-L6-v2 | Local embedding model |
EMBEDDING_CACHE_TTL | ❌ | 86400 | Embedding cache TTL in seconds (24h) |
LLM_MODEL | ❌ | Qwen/Qwen2.5-72B-Instruct | HuggingFace model for answer generation |
LLM_TEMPERATURE | ❌ | 0.3 | LLM sampling temperature |
RERANKER_MODEL | ❌ | BAAI/bge-reranker-v2-m3 | Cross-encoder reranker model |
USE_HYBRID_SEARCH | ❌ | True | Enable BM25 + vector hybrid search |
RRF_K | ❌ | 60 | RRF smoothing constant |
CHUNK_SIZE | ❌ | 1000 | Characters per document chunk |
CHUNK_OVERLAP | ❌ | 200 | Overlap between consecutive chunks |
TOP_K_RETRIEVAL | ❌ | 20 | Candidates retrieved from vector store |
TOP_K_RERANK | ❌ | 8 | Final chunks after reranking |
VISION_PROVIDER | ❌ | — | Set to openai to use GPT-4o-mini for image captions |
OPENAI_API_KEY | ❌ | — | Required when VISION_PROVIDER=openai |
ENVIRONMENT | ❌ | development | Set to production to lock CORS |
FRONTEND_URL | ❌ | http://localhost:3000 | Public frontend URL for OAuth + email links |
NEXT_PUBLIC_API_URL | ❌ | http://localhost:7860 | Backend URL injected at frontend build time |
<br/>
📡 API Reference
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /api/v1/auth/register | ❌ | Create a new user account |
POST | /api/v1/auth/login | ❌ | Login and receive JWT tokens |
GET | /api/v1/auth/me | ✅ | Get current user profile |
POST | /api/v1/documents/upload | ✅ | Upload PDF/DOCX/TXT and enqueue ingestion (202) |
POST | /api/v1/documents/urlupload | ✅ | Crawl a URL and ingest as document |
GET | /api/v1/documents/ | ✅ | List documents (pagination + ?q= name filter) |
GET | /api/v1/documents/{id} | ✅ | Get document metadata (incl. extracted URLs) |
GET | /api/v1/documents/{id}/status | ✅ | Poll ingestion progress |
DELETE | /api/v1/documents/{id} | ✅ | Soft-delete document |
POST | /api/v1/chat/ask/stream | ✅ | Ask a question (SSE streaming) |
GET | /api/v1/chat/history/{doc_id} | ✅ | Get chat history for a document |
DELETE | /api/v1/chat/history/{doc_id} | ✅ | Clear chat history |
GET | /api/v1/chat/export/{doc_id} | ✅ | Export transcript as MD / TXT / PDF |
GET | /api/v1/chat/sessions | ✅ | List chat sessions |
POST | /api/v1/chat/sessions | ✅ | Create chat session |
GET | /api/v1/health/status | ❌ | Deep health check (DB, Redis, Celery, ChromaDB) |
GET | /api/health | ❌ | Basic liveness check |
Full interactive docs at /docs (Swagger UI) when running locally.
<br/>
AI / ML Pipeline
| Technology | Purpose | |
|---|---|---|
| <img src="https://img.shields.io/badge/sentence--transformers-000000?style=flat" height="24"/> | **sentence-transformers (all-MiniLM-L6-v2)** | Generates vector embeddings for document chunks |
| <img src="https://img.shields.io/badge/ChromaDB-000000?style=flat" height="24"/> | **ChromaDB** | Stores + retrieves embeddings locally |
| <img src="https://img.shields.io/badge/HuggingFace-FFD21E?style=flat&logo=huggingface&logoColor=black" height="24"/> | **HuggingFace Inference API** | Generates answers from retrieved context |
| <img src="https://img.shields.io/badge/Cross--Encoder-000000?style=flat" height="24"/> | **BAAI/bge-reranker-v2-m3** | Cross-encoder reranking for retrieval quality |
| <img src="https://img.shields.io/badge/GraphRAG-000000?style=flat" height="24"/> | **Knowledge Graph (GraphRAG)** | Entity extraction + relationship graphs |
| <img src="https://img.shields.io/badge/PyMuPDF-FF0000?style=flat" height="24"/> | **PyMuPDF + pdfplumber + python-docx** | Document text extraction |
🤖 RAG Pipeline
- 🔪 Smart recursive text chunking (configurable size & overlap)
- 🧠 Local embeddings — no data leaves your machine
- ⚡ Embedding cache (Redis + LRU) — skip redundant computation
- 🔍 Hybrid search — vector + BM25 merged via RRF
- 🏆 Cross-encoder reranking for precision answers
- 🖼️ Image caption extraction from PDF figures
- 🔗 URL extraction from PDF link annotations
- 🗺️ Knowledge graph (GraphRAG) per document
</td> <td width="33%" valign="top">
🧠 RAG Pipeline
┌─────────────────────────────────────────────┐
│ PDF / DOCX / TXT / MD Upload │
└───────────────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ PyMuPDF / pdfplumber / python-docx Parser │
│ + Image caption extraction │
│ + PDF URL/link annotation extraction │
└───────────────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Recursive Character Text Splitter │
│ chunk_size=1000 | overlap=200 │
└───────────────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ all-MiniLM-L6-v2 (local embeddings) │
│ 384-dim · Redis + LRU cache (24h TTL) │
└──────────────┬──────────────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌──────────────────┐ ┌─────────────────────┐
│ ChromaDB vectors │ │ BM25 keyword index │
│ (per-user coll.) │ │ (per-document .pkl)│
└──────────────────┘ └─────────────────────┘
── At Query Time ──
User Question ──▶ Embed (cached) ──▶ Vector Search (Top-K=20)
│
├──▶ BM25 Search (Top-K=20)
│
▼
Reciprocal Rank Fusion (RRF, k=60)
│
▼
BGE-Reranker-v2-m3 Cross-Encoder (Top-K=8)
│
▼
Prompt Assembly (system + context + question)
│
▼
Qwen2.5-72B-Instruct (HF Inference API)
│
▼
Streamed SSE tokens ──▶ Frontend ChatPanel<br/>
PDF-Assistant-RAG 是一个面向企业级应用的 Agentic RAG 文档助手。它能够处理复杂的 PDF、财务报告、法律合同及研究论文，并通过多阶段 Retrieval-Augmented Generation 流水线，为用户提供具备准确引用来源的 AI 对话体验。系统结合了语义搜索与 Cross-encoder 重排序技术，确保检索结果的高度相关性与回答的严谨性。
本项目集成了先进的 RAG 技术栈，支持智能递归文本分块（Recursive Text Chunking），并采用本地 Embedding 技术确保数据隐私。通过两阶段检索机制（语义搜索 + Cross-encoder Rerank）与 Top-K 过滤，系统能够实现高精度的问答，并能根据自定义 System Prompts 生成带有原文引用的专业回答。
在开始部署之前，请确保您的开发环境已安装以下必要组件：Python 3.11+ 用于后端逻辑处理，Node.js 20+ 用于前端界面运行，以及 HuggingFace Token 用于调用 LLM 推理 API。此外，建议使用 Docker 环境以简化复杂的依赖管理。
您可以根据需求选择多种部署方式。推荐使用 Docker 进行快速部署，只需运行 `docker compose up --build` 即可构建并启动全栈服务；若需进行二次开发，也可通过源码方式安装，手动配置 Python 与 Node.js 环境并安装相关依赖。
项目启动后，用户可以通过 Web 界面上传 PDF 文档。系统会自动进行文档解析与向量化处理。用户可以直接在对话框中针对文档内容进行提问，AI 将基于检索到的上下文片段进行回答，并标注出信息来源的引用位置，方便用户核实。
在运行前，必须配置环境变量以确保系统正常工作。请将 `.env.example` 复制为 `backend/.env` 并进行编辑。关键参数包括用于 JWT 签名的 `SECRET_KEY`、数据库连接地址 `DATABASE_URL` 以及用于调用 HuggingFace Inference API 的 `HF_TOKEN`。请务必妥善保管您的 Token 信息。
本项目提供了一套完整的 RESTful API 接口，支持用户注册 (`/api/v1/auth/register`)、登录 (`/api/v1/auth/login`) 以及获取当前用户信息 (`/api/v1/auth/me`)。所有受保护的接口均需通过 JWT Token 进行身份验证，确保了企业级应用的安全访问控制。
系统的 AI/ML 流水线采用了严谨的设计：首先利用 `all-MiniLM-L6-v2` 模型进行本地化句子嵌入（Embeddings），确保数据不出本地；随后通过语义搜索初步检索，并使用 `ms-marco-MiniLM-L-6-v2` Cross-encoder 进行重排序（Rerank），最后结合 Top-K 过滤与带有引用指令的 System Prompts，实现精准的 RAG 问答流程。
高质量的PDF处理工具，值得推荐
- 构建多智能体协作系统的 Agent 开发者
- 构建企业知识库 / RAG 检索应用的团队
- 生产部署优先使用 Docker Compose 隔离依赖，并挂载 volume 持久化数据
- 分块大小建议 256-512 tokens，向量库优选 pgvector 或 Qdrant
- Agent 任务先做 dry-run 验证工具调用链，再开启自主执行
- API key 直接提交到 git 仓库（请用 .env 并加入 .gitignore）
- 容器内无法访问宿主机 localhost — 使用 host.docker.internal
- embedding 模型与查询模型不一致导致检索失效
- Python 依赖冲突：建议用 venv / uv 隔离环境
- Docker：PDF-Assistant-RAG 提供官方镜像，docker compose up 一键启动
- CLI：直接 npm install -g / pip install，命令行调用
- 云端托管：可放在 Vercel / Railway / Fly.io 等 PaaS 平台
⚡ 核心功能
- 开源免费，支持本地部署，数据完全自主可控
- 活跃的 GitHub 开源社区，持续迭代更新
- 提供详细文档和使用示例，新手友好
- 支持自定义配置，灵活适配不同使用环境
- 可作为基础组件集成进现有技术栈或进行二次开发
- 构建多智能体协作系统的 Agent 开发者
- 构建企业知识库 / RAG 检索应用的团队
- 生产部署优先使用 Docker Compose 隔离依赖，并挂载 volume 持久化数据
- 分块大小建议 256-512 tokens，向量库优选 pgvector 或 Qdrant
- Agent 任务先做 dry-run 验证工具调用链，再开启自主执行
- API key 直接提交到 git 仓库（请用 .env 并加入 .gitignore）
- 容器内无法访问宿主机 localhost — 使用 host.docker.internal
- embedding 模型与查询模型不一致导致检索失效
- Python 依赖冲突：建议用 venv / uv 隔离环境
👥 适合人群
🎯 使用场景
- 本地部署运行，保护数据隐私，满足合规要求
- 自定义集成到现有系统，扩展技术栈能力
- 作为开源基础组件进行商业化二次开发
⚖️ 优点与不足
- +MIT 协议，可免费商用
- +完全开源免费，无授权费用
- +本地部署，数据完全自主可控
- +开发者社区支持，遇问题可查可问
- −安装和初始配置可能需要一定技术基础
- −功能完整性通常不如成熟商业产品
- −技术支持主要依赖开源社区，响应速度不稳定
AI Skill Hub 为第三方内容聚合平台，本页面信息基于公开数据整理，不对工具功能和质量作任何法律背书。
建议在沙箱或测试环境中充分验证后，再部署至生产环境，并做好必要的安全评估。
✅ MIT 协议 — 最宽松的开源协议之一，可自由商用、修改、分发，仅需保留版权声明。
🔗 相关工具推荐
❓ 常见问题 FAQ
总体来看，PDF-Assistant-RAG AI技能包 是一款质量优秀的AI工具，在同类工具中具备一定竞争力。AI Skill Hub 将持续追踪其更新动态，建议收藏备用，结合自身场景选择合适时机引入使用。
| 原始名称 | PDF-Assistant-RAG |
| 原始描述 | 开源AI工具：PDF-Assistant-RAG is a complete, production-ready AI document assistant that let。⭐12 · TypeScript |
| Topics | pdftypescriptfastapinextjs |
| GitHub | https://github.com/param20h/PDF-Assistant-RAG |
| License | MIT |
| 语言 | TypeScript |
收录时间：2026-05-18 · 更新时间：2026-05-19 · License：MIT · AI Skill Hub 不对第三方内容的准确性作法律背书。