| name | deepseek-v4-flash-vision-rag |
| description | 基于DeepSeek视觉大模型（deepseek-v4-flash-vision-exp）的PDF深度问答与检索（vision RAG）。当用户提到 PDF、文档、资料、报告、论文、电子书、手册、说明书，并想提问、查找、搜索、总结或理解其内容，或问"在哪一页"、"引用原文"、要页面截图时，使用本skill。支持扫描版、图表、表格、代码的视觉理解；回答带物理页码引用，并把命中页原图展示给用户。 |
DeepSeek V4-Flash Vision RAG
用 DeepSeek 视觉大模型"看懂"整份 PDF：先为每页建立视觉索引（一次性、缓存复用），
再对用户问题做 本地粗筛 → 视觉精排 → 深读回答，回答带 [第N页] 引用，
并把命中页图片展示给用户。
相比逐段文本 RAG，它直接看页面图像，因此能理解排版、图表、表格、代码块，
扫描版也能用；页码来自渲染本身，天然精确。
环境
- Python 依赖：
openai、pymupdf(fitz)（本机已装；缺了先 pip install）
- API key：默认已内置；可用环境变量
DEEPSEEK_API_KEY 覆盖
- 所有脚本在
scripts/ 下，Windows 下可直接 python scripts/xxx.py
工作流
第 1 步：建立索引（每份 PDF 一次，之后走缓存）
python scripts/ingest.py "<pdf路径>"
- 渲染每页 → Files API 上传 → 分批视觉分析 → 落盘
scripts/.cache/<sha>/index.json
- 120 页约 3–5 分钟、5 次模型调用；重复运行直接命中缓存
- 常用参数：
--force 重建索引；--limit N 只索引前 N 页（大文档先试水）；
--clean 删本地缓存
- 输出会打印页型分布（正文/目录/附录…）和大纲条数，可据此向用户简报文档结构
第 2 步：回答用户问题
python scripts/ask.py "<pdf路径>" "用户的问题"
- 流程：本地 TF-IDF 粗筛 top12 → 视觉精排选 top4（1 次调用）→ 命中页±1 深读
（1 次调用，开推理）→ 输出带
[第N页] 引用的答案
- 可调：
--top K 深读页数；--cands N 粗筛候选数；--no-images 不复制图片
脚本 stdout 分四段：=== 答案 ===、=== 引用页 ===、=== 页面图片 ===（图片
已复制到 ./pdf-vision-out/<书名>_p<N>.png）。
第 3 步：向用户展示页面原图（必须做）
终端里用户未必能看到 inline 图片，所以必须给出用户自己能打开的路径，按优先级：
- HTML 预览（首选）：ask.py 自动在
./pdf-vision-out/ 生成 <书名>_<问题>.html
——自包含单文件（答案 + 全部引用页原图 base64 内嵌），把路径告诉用户，
双击即可在浏览器查看，无需联网。Windows 下也可代用户执行 start "<路径>" 打开。
- 单页 PNG 路径：
./pdf-vision-out/<书名>_p<N>.png，用户只要某几页时逐张给出。
- 支持 inline 图片的环境（如 ZCode）可再用 Read 工具读取 PNG，把图渲染进对话作为
补充；但不得只依赖这种方式——Read 的图用户端可能不显示。
用户想直接看某几页时：
python scripts/show.py "<pdf路径>" --pages 6,7 [--dpi 220]
然后把输出的 PNG 路径给用户（同样可 start 打开）。
回答规范
- 以脚本产出的答案为事实基础，组织成简洁中文回答；保留
[第N页] 引用标记
- 答案与引用页不符、或脚本说明"内容不足"时，如实告诉用户，不要编造
- 展示原图时必须提供用户可自行打开的本地路径（HTML 预览或 PNG），不能只靠
inline 展示
- 可以顺带告诉用户引用页码，方便他翻原 PDF 对照
注意事项
- 首次 ingest 慢（分钟级）是正常的；告知用户后续提问秒级响应
--limit 建过的索引是部分的，之后不带 --limit 重跑会自动补全- API 细节（推理开关、384 token/图、Files API 限制等坑）见
references/api-notes.md，改 scripts/ds_client.py 前必读
- 索引/缓存结构见
references/index-schema.md
