PDF问答机器人

Prerequisites

Optional but recommended:

• Git — clone and contribute
• CUDA-capable GPU — faster Hugging Face inference (CPU works, slower)
• 8 GB+ RAM — model loading and FAISS indexing

---

Prerequisites

• Docker
• Docker Compose

Python / dependency issues

---

Installation

Install dependencies in all three locations. Use three separate terminal sessions when running locally.

activate venv (see Installation)

uvicorn main:app --host 0.0.0.0 --port 5000 --reload

Alternative:

Running with Docker

You can run the entire multi-service application easily using Docker Compose. This ensures reproducibility and eliminates the need to install Python, Node.js, and dependencies manually on your host machine.

Quick Start

1. Clone the repository and navigate to the project root.
2. Build and start all services in detached mode:

docker-compose up -d --build

3. The services will be available at: - Frontend UI: http://localhost:3000 - Express API Gateway: http://localhost:4000 - FastAPI RAG Service: http://localhost:5000

Note on Initial Startup: On the first run, the RAG service container will download the necessary Hugging Face models (~1GB total). These models are cached in a persistent Docker volume (pdf-qa-bot-hf-cache) so they will not be re-downloaded on subsequent restarts.

From rag-service/, after activating the venv

cp ../.env.example .env # macOS / Linux copy ..\.env.example .env # Windows (cmd) Copy-Item ..\.env.example .env # Windows (PowerShell) ```

Edit .env if you want a smaller or faster generation model (see Configuration).

Configuration

Environment variables are read from rag-service/.env (create from .env.example at the repo root).

Faster, lighter generation (recommended on CPU-only machines):

HF_GENERATION_MODEL=google/flan-t5-small

Optional frontend override — set before npm start in frontend/:

REACT_APP_API_URL=http://localhost:4000

Leave unset to use the CRA dev proxy (/upload → http://localhost:4000/upload).

---

activate venv

python -c "from langchain_community.embeddings import HuggingFaceEmbeddings; HuggingFaceEmbeddings(model_name='sentence-transformers/all-MiniLM-L6-v2')" python -c "from transformers import AutoTokenizer, AutoModelForSeq2SeqLM; AutoTokenizer.from_pretrained('google/flan-t5-base'); AutoModelForSeq2SeqLM.from_pretrained('google/flan-t5-base')"

Set a custom cache directory if needed:

2. Express API (repository root)

cd ..          # repository root (parent of rag-service/)
npm install

Multer writes uploads to an uploads/ directory at runtime; it is created automatically on first upload.

Terminal 2 — Express API

```bash

API Reference

Express API (`http://localhost:4000`)

Public-facing routes used by the React app. All paths are relative to the gateway origin.

Example — upload (curl)

curl -X POST http://localhost:4000/upload \
  -F "file=@/path/to/document.pdf"

Example — ask

curl -X POST http://localhost:4000/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"What is the main topic?","session_id":"<uuid-from-upload>"}'

---

FastAPI RAG service (`http://localhost:5000`)

Internal service called by Express. You can call it directly for debugging.

Interactive OpenAPI docs: http://localhost:5000/docs (recommended for local development only; do not expose publicly)

Example — process PDF (via gateway, recommended)

curl -X POST http://localhost:4000/upload \
  -F "file=@/path/to/your.pdf"

---

Frontend cannot reach the API

---

PDF Q&A Bot

Upload PDF documents, ask natural-language questions grounded in their content, and generate concise summaries — all through a local, three-service stack. The React UI talks to a Node.js API gateway, which orchestrates a Python RAG (retrieval-augmented generation) service powered by Hugging Face embeddings and a configurable text-generation model.

---

Troubleshooting