PDF 文档
  │
  ▼ (PyMuPDF, 150 DPI)
页面图片（不做任何文本提取）
  │
  ▼ (Embedding API, 云端调用)
  │   ├─ Cohere embed-v4.0 → 1 个 1024 维向量
  │   └─ DashScope tongyi-embedding-vision-plus → 1 个 1152 维向量
每页图片 → 1 个向量
  │
  ▼ (写入 Zilliz Serverless 云向量数据库)
doc_name + page_idx + vector
  │
  ══════════════ 用户提问时 ══════════════
  │
  ▼ (Embedding API 编码查询文本)
查询 → 1 个向量
  │
  ▼ (Zilliz 内积相似度搜索)
Top-K 最相关页面
  │
  ▼ (页面原始图片 + 问题 → 视觉大模型生成回答)
  │   ├─ DashScope: qwen3.5-flash / qwen3.5-plus / qwen3-vl-plus（国内推荐）
  │   └─ OpenRouter: qwen/qwen3.5-397b-a17b（海外可用）
AI 直接"看图"回答问题

D:/PDF-AI/
├── .env                    # 密钥和连接配置（不入库）
├── .env.example            # 配置模板
├── .gitignore
├── requirements.txt        # Python 依赖（9 个包，无 PyTorch）
├── config.py               # 配置中心，从 .env 加载
├── app.py                  # Flask Web 服务 + API 路由（端口 7860）
├── api_server.py           # 独立 API 问答服务（端口 7861，供外部调用）
├── static/
│   └── index.html          # 前端页面
│
├── core/
│   ├── embedder.py         # 双引擎 Embedding（Cohere / DashScope）+ 工厂函数
│   ├── vector_store.py     # Zilliz 向量库：集合管理、插入、搜索
│   ├── retriever.py        # 单向量检索：编码查询 → 搜索 Zilliz → Top-K 页面
│   └── generator.py        # 双引擎 LLM 生成（DashScope / OpenRouter）
│
└── utils/
    ├── pdf_processor.py    # PDF 转图片（PyMuPDF 封装，无需 poppler）
    └── image_utils.py      # 图片转 base64（data URI 供 Cohere，纯 base64 供 DashScope）

POST http://127.0.0.1:7861/api/query
Content-Type: application/json

{
    "question": "什么是积木？",
    "doc_name": "LEGO.pdf"
}

GET http://127.0.0.1:7861/api/docs

┌─────────────────────────────────────────────────────┐
│  data/uploads/  (本地磁盘)                            │
│  ├── report.pdf          原始 PDF 文件，持久保存        │
│  ├── paper.pdf           服务重启/页面刷新后仍在        │
│  └── ...                                             │
├─────────────────────────────────────────────────────┤
│  Zilliz Cloud  (云端向量库)                           │
│  集合: pdf_rag_cohere / pdf_rag_dashscope（按引擎自动选择）│
│  每条记录: doc_name + page_idx + vector(由引擎决定维度)│
│  已 encode 的文档向量永久保存，不受重启影响             │
├─────────────────────────────────────────────────────┤
│  内存 (_image_cache)  (进程级缓存)                     │
│  doc_name → [PIL.Image, PIL.Image, ...]              │
│  加速图片访问，按需从 PDF 重新加载                      │
└─────────────────────────────────────────────────────┘

集合名: pdf_rag_cohere (Cohere) / pdf_rag_dashscope (DashScope)
  (可通过 .env 的 COHERE_COLLECTION_NAME / DASHSCOPE_COLLECTION_NAME 配置)

字段:
  id       INT64       自增主键
  doc_name VARCHAR(256) PDF 文件名，用于区分不同文档
  page_idx INT64       页码（从 0 开始）
  vector   FLOAT_VECTOR(N)     N 由引擎决定：Cohere 1024 / DashScope 1152

索引:
  字段: vector
  类型: IVF_FLAT
  相似度: IP (内积)
  参数: nlist=128, nprobe=10

用户选择 PDF 文件
  │
  ▼ POST /api/upload
Flask 接收文件，保存到 data/uploads/{filename}.pdf
  ├── 同名文件会被覆盖
  └── 清除该文档的内存图片缓存
  │
  ▼ 前端下拉框显示文档名
  │
用户点击 "Encode & Index"
  │
  ▼ POST /api/encode {doc_name: "xxx.pdf"}
  │
  ├── Step 1: PDF → 图片
  │   PyMuPDF (fitz) 打开 PDF，逐页渲染为 RGB 图片
  │   DPI 由 config.pdf_dpi 控制（默认 150）
  │   图片缓存在内存 _image_cache[doc_name]
  │
  ├── Step 2: 图片 → 向量 (Embedding API)
  │   将每张图片缩放到 max_image_size (默认 1200px)
  │   ├─ DashScope: 转为 JPEG base64，按 8 张/批调用 MultiModalEmbedding.call()
  │   │   模型: tongyi-embedding-vision-plus，产出 1152 维向量
  │   └─ Cohere: 转为 JPEG base64 data URI，按 96 张/批调用 embed()
  │       模型: embed-v4.0，input_type=search_document，产出 1024 维向量
  │   每页产出 1 个向量（维度由引擎决定）
  │
  └── Step 3: 写入 Zilliz
      每页一条记录: {doc_name, page_idx, vector}
      如果该文档之前已 encode 过，向量会重复插入
      （建议 clear 后重新 encode，或后续优化为 upsert）

用户输入问题，点击 "Search & Answer"
  │
  ▼ POST /api/search {question: "...", doc_name: "xxx.pdf" | "__all__"}
  │
  ├── Step 1: 查询编码 (Embedding API)
  │   ├─ DashScope: MultiModalEmbedding.call(input=[{text: ...}]) → 1152 维
  │   └─ Cohere: embed(texts=[...], input_type="search_query") → 1024 维
  │   问题文本 → 1 个向量
  │
  ├── Step 2: 向量搜索 (Zilliz)
  │   用查询向量在 Zilliz 中做内积相似度搜索
  │   如果指定了 doc_name，添加过滤条件 filter='doc_name == "xxx"'
  │   如果选 "All Documents"，不加过滤，跨文档搜索
  │   返回 Top-K (默认 3) 条结果，每条包含 doc_name + page_idx + score
  │
  ├── Step 3: 页面扩展 ±2
  │   图书内容通常是连续的，一个主题可能跨越多页
  │   对每个命中页，取其前后各 2 页（即 ±2，共 5 页）
  │   自动去重：如果两个命中页距离 ≤4 页，交集部分不重复
  │   自动边界检查：不会超出 PDF 实际页数
  │   示例：命中第 18 页 → 展开为第 16、17、18、19、20 页
  │
  ├── Step 4: 加载页面图片
  │   根据 (doc_name, page_idx) 获取页面图片:
  │   优先从内存缓存 _image_cache 读取
  │   缓存未命中时，从 data/uploads/{doc_name} 用 PyMuPDF 按需加载
  │   图片转 PNG base64，返回给前端展示
  │
  └── Step 5: LLM 生成回答
      构建多模态消息:
      content = [
        {type: "image_url", image_url: {url: "data:image/png;base64,..."}},
        ...每张检索到的页面图片...
        {type: "text", text: "Above are N retrieved document pages. Question: ..."}
      ]
      ├─ DashScope (默认): 调用 dashscope.aliyuncs.com OpenAI 兼容接口
      │   模型: qwen3.5-flash / qwen3.5-plus / qwen3-vl-plus 等
      └─ OpenRouter: 调用 openrouter.ai
          模型: qwen/qwen3.5-397b-a17b
      超时: 120 秒
      LLM 直接"看"页面图片生成回答

用户点击 "Clear All"
  │
  ▼ POST /api/clear
  │
  ├── 删除 Zilliz 集合并重建空集合
  ├── 删除 data/uploads/ 下所有 PDF 文件
  └── 清空内存图片缓存

app.py (Flask Web 服务:7860, 5 个 API 路由 — 文档管理 + 问答)
api_server.py (独立 API 服务:7861, 2 个 API 路由 — 问答接口，供外部调用)
  ├── config.py (配置中心, 从 .env 加载变量)
  ├── utils/pdf_processor.py (PDF → 图片, PyMuPDF)
  ├── core/vector_store.py (Zilliz 操作)
  ├── core/embedder.py (双引擎 Embedding: Cohere / DashScope, create_embedder() 工厂)
  │     ├── utils/image_utils.py (图片 → base64, data URI / 纯 base64 两种格式)
  │     └── config.py
  ├── core/retriever.py (单向量检索)
  │     ├── core/embedder.py
  │     └── core/vector_store.py
  └── core/generator.py (双引擎 LLM: DashScope / OpenRouter)
        ├── utils/image_utils.py
        └── config.py