kotaemon 如何配置 PDF_JS 实现浏览器内 PDF 预览？
【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon
kotaemon 的 RAG 问答自带引用标注，但要在浏览器里直接预览 PDF 原文并高亮引用位置，需要额外启用其内置的PDF_JS（PDF.js）查看器。README 将这一步标注为可选步骤：完成配置后，LLM 回答中的 citations（含相关度分数）会直接渲染在浏览器内的 PDF 查看器中。本文适用于非 Docker 的源码安装方式（Python >= 3.10），以及想了解一键安装脚本和 Docker 镜像中该功能如何被预置的读者。
机制：为什么是libs/ktem/ktem/assets/prebuilt目录
应用启动时从PDFJS_PREBUILT_DIR配置读取 PDF.js 前端资源目录。该配置定义在 assets/init.py：
PDFJS_VERSION_DIST: str = config("PDFJS_VERSION_DIST", "pdfjs-4.0.379-dist") PDFJS_PREBUILT_DIR: Path = config( "PDFJS_PREBUILT_DIR", Path(__file__).parent / "prebuilt" / PDFJS_VERSION_DIST )默认值指向libs/ktem/ktem/assets/prebuilt/pdfjs-4.0.379-dist。pdf_viewer.js 中的查看器元素通过viewer-path="GR_FILE_ROOT_PATH/file=PDFJS_PREBUILT_DIR"从该目录加载资源，所以目录名和位置必须与配置一致，否则查看器无法工作。仓库中所有脚本和 Dockerfile 固定使用 PDF.js4.0.379版本。
准备条件
克隆仓库并进入项目根目录：
git clone https://github.com/Cinnamon/kotaemon cd kotaemon创建 Python 3.10 环境，二选一（见 README.md 的 Without Docker 一节）：
# 方式一：uv（推荐） uv sync --python 3.10 source .venv/bin/activate# 方式二：conda conda create -n kotaemon python=3.10 conda activate kotaemon pip install -e "libs/kotaemon[all]" pip install -e "libs/ktem"
主路径：手动下载并解压 PDF_JS_DIST
README 给出的原始要求是：下载 PDF_JS_DIST 并解压到libs/ktem/ktem/assets/prebuilt。对应命令如下（下载地址与仓库文档一致）：
curl -L -o pdfjs-4.0.379-dist.zip \ https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip mkdir -p libs/ktem/ktem/assets/prebuilt unzip -o pdfjs-4.0.379-dist.zip -d libs/ktem/ktem/assets/prebuilt解压完成后，检查目录结构应出现libs/ktem/ktem/assets/prebuilt/pdfjs-4.0.379-dist/（zip 包根目录名即pdfjs-4.0.379-dist，与默认配置PDFJS_VERSION_DIST一致）。目录层级错了查看器就会失效，这一步是整个配置的关键。
可选方式：使用仓库自带脚本 download_pdfjs.sh
scripts/download_pdfjs.sh 封装了同样的下载与解压逻辑，版本同样固定为4.0.379。它接收一个参数：目标目录（脚本内变量名为pdfjs_version_dist），在项目根目录执行：
bash scripts/download_pdfjs.sh libs/ktem/ktem/assets/prebuilt/pdfjs-4.0.379-dist使用该脚本前需注意脚本的实际行为：
- 检查当前工作目录路径是否含空格，含空格会直接报错退出；
- 若目标目录已存在，打印 "Skipping download" 并跳过（幂等，可重复执行）；
- 依赖
curl和unzip；下载完成后会删除中间产物downloaded.zip； - 脚本只负责放置文件，不会启动应用，也不会改动其他目录。
可选：用环境变量指定其他目录
如果你把 PDF.js 资源放在默认位置之外，需要在启动时用PDFJS_PREBUILT_DIR环境变量指明目录。仓库的一键脚本 run_linux.sh、run_macos.sh 就是按这个方式启动的（Dockerfile 中同样用ENV PDFJS_PREBUILT_DIR覆盖了目录）。对应的手动启动命令：
PDFJS_PREBUILT_DIR=libs/ktem/ktem/assets/prebuilt/pdfjs-4.0.379-dist python app.py按主路径解压到默认位置时，不设该变量也可直接启动。
启动与验证
在项目根目录启动 Web 服务：
python app.py应用会自动在浏览器中打开，默认用户名和密码均为
admin。验证功能是否生效：上传一个
.pdf文档并在聊天中提问，回答中的 citations（含相关度分数）会在浏览器内 PDF 查看器中直接展示并高亮。这是 README Key Features 中 "Advanced citations with document preview" 描述的效果，也是本功能启用后的预期现象。若查看器不显示 PDF，先核对两点：解压后的目录名是否为
pdfjs-4.0.379-dist且位于libs/ktem/ktem/assets/prebuilt/下；如资源放在其他位置，是否设置了PDFJS_PREBUILT_DIR。
一键安装脚本与 Docker 镜像中的处理
scripts/run_linux.sh、scripts/run_macos.sh（Windows 为scripts/run_windows.bat）这类一键脚本在流程中会自动把 PDF.js 下载到libs/ktem/ktem/assets/prebuilt/pdfjs-4.0.379-dist并在启动 UI 时设置PDFJS_PREBUILT_DIR。但注意副作用：这些脚本还会安装 Miniconda、创建 conda 环境、安装全部依赖并通过scripts/serve_local.py配置本地模型，属于完整安装流程，不建议仅为了启用 PDF 预览单独运行，也不要在已装好环境的情况下重复执行。- Docker 用户无需任何额外配置：Dockerfile 在构建镜像时执行
RUN bash scripts/download_pdfjs.sh $PDFJS_PREBUILT_DIR，把 PDF.js 预置到镜像内的/app/libs/ktem/ktem/assets/prebuilt/pdfjs-dist。按 README 的docker run ... ghcr.io/cinnamon/kotaemon:main-lite方式运行后访问http://localhost:7860/，浏览器内 PDF 预览开箱可用。
限制说明
- PDF.js 版本在各处脚本与配置中固定为
4.0.379；README 的下载地址与默认配置目录名均基于该版本，更换版本时目录名需与PDFJS_VERSION_DIST/PDFJS_PREBUILT_DIR配置保持对应。 - 该功能是 README 明确标注的 Optional 步骤，不配置不影响 kotaemon 的其他功能，只是无法在浏览器内直接预览 PDF 与引用高亮。
- 若通过
uv或conda手动管理环境，只需执行"准备条件 + 主路径（或脚本方式）+ 启动验证"三步；.env、GraphRAG、本地模型等 README 中的其他配置项与本任务无关，可跳过。
【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
