jina-ai--reader/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Reader

你的 LLM 值得获得更好的输入。

Reader 提供两项能力：

• Read（读取）：它将任意 URL 转换为适合 LLM 使用的输入，采用 https://r.jina.ai/https://your.url。无需额外成本，即可为你的智能体（agent）和 RAG 系统获得更优的输出。
• Search（搜索）：它使用 https://s.jina.ai/your+query 针对给定查询搜索网络。这使你的 LLM 能够访问来自网络的最新世界知识。

请查看在线演示

或直接访问这些 URL（Read）https://r.jina.ai/https://github.com/jina-ai/reader,（Search）https://s.jina.ai/Who%20will%20win%202024%20US%20presidential%20election%3F 亲自体验。

欢迎在生产环境中使用 Reader API。它免费、稳定且可扩展。我们将其作为 Jina AI 的核心产品之一积极维护。查看速率限制

本仓库是 https://r.jina.ai 与 https://s.jina.ai 背后代码库的开源分支。它以无状态或 bucket 缓存模式运行；此处不包含基于 MongoDB 的 SaaS 存储层。

更新

• 2026-04 — 已将开源分支与 SaaS 代码重新同步。基于 MongoDB 的存储层已剥离；oss 分支开箱即可以无状态模式运行，并可通过 docker compose 可选启用 MinIO/S3 兼容的 bucket 缓存。参见本地开发。
• 2025-12 — 存储层解耦，并支持二进制文件上传。PDF 及 MS Office 文档（Word、Excel、PowerPoint）现可直接通过 file 请求体字段 POST 上传——无需事先托管。参见 cookbooks.md。
• 2025-03 — 重大重构：Reader 不再是 Firebase 应用。SaaS 已从 Firestore + Cloud Functions 迁移至搭载 MongoDB Atlas 的 Cloud Run 镜像，移除了与平台耦合的部分，并打通了上文所述的本地 Docker 路径。
• 2024-05 — s.jina.ai 上线，将 Reader 从 URL→markdown 扩展至 search→markdown。同月新增 PDF 支持——任何以 .pdf 结尾的 URL 均使用 PDF.js 解析并返回为 markdown。
• 2024-04 — Reader 发布，r.jina.ai 作为 Jina AI 首个将 URL 转换为 LLM 友好输入的 SaaS API 正式上线。

Reader 可读取的内容

• 网页 — 通过无头 Chrome 渲染，或通过 curl-impersonate 轻量抓取。Reader 会智能地在两者之间选择。
• PDF — 任意 URL，使用 PDF.js 解析。查看此 NASA PDF 结果 与原始文件.
• MS Office 文档 — Word、Excel、PowerPoint，经 LibreOffice 转换后按 HTML/PDF 处理。
• 图片 — 由视觉-语言模型（vision-language model）生成说明文字，使你的下游纯文本 LLM 获得恰到好处的提示以进行推理。

用法

使用 r.jina.ai 抓取单个 URL

只需在任意 URL 前添加 https://r.jina.ai/ 前缀。例如，要将 URL https://en.wikipedia.org/wiki/Artificial_intelligence 转换为 LLM 友好输入，可使用以下 URL：

https://r.jina.ai/https://en.wikipedia.org/wiki/Artificial_intelligence

使用 r.jina.ai 抓取完整网站（Google Colab）

使用 s.jina.ai 进行网络搜索

只需在搜索查询前添加 https://s.jina.ai/ 前缀。注意，若在代码中使用，请先对搜索查询进行编码，例如若查询为 Who will win 2024 US presidential election?，则 URL 应如下所示：

https://s.jina.ai/Who%20will%20win%202024%20US%20presidential%20election%3F

在幕后，Reader 会搜索网络、获取前 5 条结果、访问每个 URL，并对其应用 r.jina.ai。这与许多智能体/RAG 框架中的 web search function-calling 不同——后者通常只返回搜索引擎 API 提供的标题、URL 和描述。若要对某条结果做更深入阅读，你必须自行从该 URL 抓取内容。使用 Reader 时，http://s.jina.ai 会自动为你从前 5 条搜索结果 URL 抓取内容（复用 http://r.jina.ai 背后的技术栈）。这意味着你无需自行处理浏览器渲染、拦截，或与 JavaScript 和 CSS 相关的任何问题。

使用 s.jina.ai 进行站内搜索

只需在查询参数中指定 site，例如：

curl 'https://s.jina.ai/When%20was%20Jina%20AI%20founded%3F?site=jina.ai&site=github.com'

交互式代码片段构建器

我们强烈建议使用代码构建器探索 Reader API 的不同参数组合。

使用请求头

你可以通过请求头控制 Reader API 的行为。下列列表涵盖最实用的选项——完整接口及最新默认值与校验规则，请参见 https://r.jina.ai/docs, 上的在线 API 文档，或 src/dto/crawler-options.ts 中的权威源码。

• x-respond-with — 选择输出格式。

  • markdown 返回 markdown，不经过 readability

  • html 返回 documentElement.outerHTML

  • text 返回 document.body.innerText

  • screenshot 返回网页截图的 URL

  • pageshot 类似于 screenshot，但会尝试截取整页而非仅视口

  • frontmatter 返回带 YAML frontmatter 块的 Markdown。默认纯文本响应使用自定义的 Title: … / URL Source: … 头格式；frontmatter 会将其替换为 front matter 块。示例：

    curl -H 'X-Respond-With: frontmatter' 'https://r.jina.ai/https://example.com'
    

    ---
    title: "Example Domain"
    description: "This domain is for use in illustrative examples."
    url: "https://example.com/"
    ---
    
    ## Example Domain
    
    This domain is for use in illustrative examples in documents. ...
    

  • markdown+frontmatter — 类似 frontmatter，但覆盖整页且不做可读性过滤。

• x-engine — 强制指定抓取引擎：browser（无头 Chrome）、curl（轻量，无 JS），或 auto（默认——浏览器与 curl 组合使用）。
• x-proxy-url — 通过你指定的代理路由流量。
• x-cache-tolerance — 整数秒；可接受的缓存页面陈旧程度。
• x-no-cache: true — 绕过缓存页面（生命周期 3600s）。等效于 x-cache-tolerance: 0。
• x-target-selector — CSS 选择器。Reader 返回匹配元素内的内容，而非整页。当自动内容提取遗漏了你所需内容时很有用。
• x-wait-for-selector — CSS 选择器。Reader 会等待匹配元素渲染完成后再返回。若已设置 x-target-selector，可省略此项以等待同一元素。
• x-timeout — 整数秒（最大 180）。设置后 Reader 不会提前返回；会等待网络空闲或直至超时。
• x-max-tokens — 整数（≥500）。裁剪响应，使其不超过该 token 数。在向固定大小的上下文窗口喂入数据时，可作为按请求的防护栏——Reader 会截断而非拒绝。
• x-token-budget — 整数。若结果内容将超过该 token 数则拒绝请求。当超出预算的输出比无输出更糟时使用（例如成本控制）。在搜索端点上会被忽略。
• x-respond-timing — 显式控制 Reader 何时愿意返回。在延迟与完整性之间权衡：
  • html — 原始 HTML 一到达即返回。不执行 JS，不等待。
  • visible-content — 可读内容可解析的瞬间即返回。仍能产出文本的最低延迟。
  • mutation-idle — 等待 DOM 变更稳定 ≥0.2s。适合首屏懒渲染的 SPA 的良好默认值。
  • resource-idle — 等待影响内容的资源加载完成（安静 ≥0.5s）。面向内容形态请求的默认启发式策略。
  • media-idle — 同时等待媒体（图片、视频、字体）加载完成。可与 screenshot / pageshot / vlm 配合使用。
  • network-idle — 完整 networkidle0。最慢，最完整。当 x-timeout ≥ 20 时隐含启用。

省略时，Reader 会根据 x-respond-with、x-timeout 和 x-with-iframe 选择其一。具体规则请参阅 src/dto/crawler-options.ts 中的 presumedRespondTiming。

• x-with-generated-alt: true — 使用 VLM（视觉语言模型）为页面上的图片生成说明文字。
• x-retain-images — 控制图片如何保留在输出中：
  • all（默认）— 为每张图片保留 ![alt](url) markdown。
  • none — 完全丢弃图片。
  • alt — 仅保留 alt 文本，不含 URL。节省 token；当下游 LLM 不需要图片链接时很有用。
• x-retain-links — 控制链接如何保留在输出中：
  • all（默认）— 保留 [text](url) markdown。
  • none — 完全丢弃链接。
  • text — 仅保留链接锚文本，丢弃 URL。最适合 embedding / 语义索引（semantic indexing）流水线，其中 URL 是噪声。
  • gpt-oss — 以 gpt-oss 的 【{id}†...】 格式输出引用，并附加带编号的 URL 页脚（同时自动启用 x-with-links-summary）。
• x-retain-media — 控制 <video>、<audio> 以及嵌入式视频 iframe（来自 YouTube、Vimeo、Bilibili 等的 <iframe>）在输出中的呈现方式：
  • link（默认）— markdown 链接，例如 [Video 1](url)。嵌入式 iframe 会重写为其规范观看 URL。遵守 x-md-link-style。
  • none — 完全丢弃媒体；非视频 iframe 回退为其内部文本内容。
  • text — 仅纯标签，例如 Video 1 或 Audio 1。不含 URL。
  • image — markdown 图片语法，例如 ![Video 1](url)。
  • html — 保留原始 HTML 元素，但剥离装饰性属性（class、id、style、data-*、aria-*）。嵌入式视频 iframe 保留其原始嵌入 src，而非规范观看 URL。
• x-with-links-summary / x-with-images-summary — 在输出末尾附加去重后的所有链接 / 图片页脚。与 x-retain-links: text 或 x-retain-images: alt 组合使用，可获得行内锚文本/alt 文本，并在末尾附带一份规范 URL 列表——当你希望模型能看到 URL 又不想在行内为此付出 token 成本时非常方便。x-with-links-summary: all 会保留所有链接，而非仅保留唯一链接。
• x-markdown-chunking — 可选启用对 markdown 响应的语义分块。返回 JSON 数组（或以  分隔的文本）形式的块，而非一整块内容：
  • true / h1 … h5 — 按给定标题级别进行基于标题的分割（例如 h3 在 #、## 和 ### 处分块）。
  • structured / s1 … s5 — 块级结构化分割。s1 最粗，s5 最细。
• x-preset — 为常见场景应用预置选项组合。预设值仅对调用方未显式设置（通过 body 或其他 header）的选项生效。示例请参阅 cookbooks.md。
  • reader — 面向向人类用户展示内容。
  • index — 面向语义索引 / embedding 流水线。
  • research — 面向需要结构化、可引用输出的 AI 研究代理。
  • agent — 面向执行日常浏览任务的 AI 代理。
  • spider — 面向递归站点爬取，并生成完整链接清单。
• x-detach-invisibles — 在快照前分离带有潜在 display:none 的元素。意味着使用浏览器引擎；禁用缓存。
• x-set-cookie — 转发 cookie 设置。带 cookie 的请求不会被缓存。
• x-md-* — 微调 markdown 输出（标题样式、列表标记、链接样式等）。请参阅 src/dto/turndown-tweakable-options.ts。

使用 r.jina.ai 抓取单页应用（Single Page Application，SPA）

如今许多网站依赖 JavaScript 框架和客户端渲染，通常称为单页应用（Single Page Application，SPA）。得益于 Puppeteer 和无头 Chrome（headless Chrome），Reader 原生支持抓取这些网站。不过，由于部分 SPA 的特定开发方式，可能需要采取一些额外预防措施。

基于 hash 路由的 SPA

根据 Web 标准定义，URL 中 # 之后的内容不会发送到服务器。为缓解此问题，请在 body 中使用 POST 并配合 url 参数：

curl -X POST 'https://r.jina.ai/' -d 'url=https://example.com/#/route'

带预加载内容的 SPA

某些 SPA（甚至有些非 SPA）会先显示预加载内容，之后再动态加载主要内容。此时 Reader 可能会抓取到预加载内容。有两种缓解方式：

# wait for network idle or until timeout
curl 'https://r.jina.ai/https://example.com/' -H 'x-timeout: 10'

# wait for a specific element
curl 'https://r.jina.ai/https://example.com/' -H 'x-wait-for-selector: #content'

# combined use of both to wait for non-existent element (which means waiting for the full timeout duration)
curl 'https://r.jina.ai/https://example.com/' -H 'x-timeout: 30' -H 'x-wait-for-selector: non-existent-element'

JSON 模式

使用 accept-header 控制输出格式：

curl -H "Accept: application/json" https://r.jina.ai/https://en.m.wikipedia.org/wiki/Main_Page

自动生成 alt

页面上所有缺少 alt 标签的图片，都可由 VLM（视觉语言模型，vision-language model）自动生成说明文字，并格式化为 ![Image [idx]: [VLM_caption]](img_URL)。这应能为下游纯文本 LLM 提供足够的线索，使其在推理、筛选和摘要中纳入这些图片：

curl -H "X-With-Generated-Alt: true" https://r.jina.ai/https://en.m.wikipedia.org/wiki/Main_Page

Cookbooks

针对各类流水线场景的配方 — RAG、语义索引、深度研究、代理式浏览、可视化快照、PDF/Office/HTML 上传等 — 请参阅 cookbooks.md。每条目都是一个简短的 curl 示例，包含适用于该场景的 header 组合，以及一段说明权衡取舍的文字。

使用 Docker 自托管

开源分支的预构建镜像已发布到 GitHub Container Registry。它捆绑了 headless Chrome、LibreOffice 和 CJK 字体，因此你可以无需自行构建即可运行 Reader。

docker pull ghcr.io/jina-ai/reader:oss

运行

该镜像暴露两个端口：

• 8080 — h2c（HTTP/2 cleartext，HTTP/2 明文）。生产级、多路复用；Cloud Run 即通过此端口通信。普通 curl 若无 --http2-prior-knowledge 将无法使用它。
• 8081 — HTTP/1.1 回退。同一处理器、同一路由；从不支持 h2c 的客户端使用此端口。

若要从 curl 或浏览器快速试用，请映射 HTTP/1.1 端口：

docker run --rm -p 3000:8081 ghcr.io/jina-ai/reader:oss
# then: curl http://localhost:3000/https://example.com

若要进行负载测试或模拟生产流量，请改映射 h2c 端口（或同时映射两者）：

docker run --rm -p 3000:8080 -p 3001:8081 ghcr.io/jina-ai/reader:oss

无需额外配置时，容器完全无状态 — 每个请求都访问实时 URL，无缓存、无限流。这对快速试用、CI 或一次性环境是合适的默认设置。

带缓存运行

将 Reader 指向 S3 兼容存储桶，以缓存已抓取的页面并在请求间复用：

docker run --rm -p 3000:8081 \
  -e GCP_STORAGE_ENDPOINT=https://s3.example.com \
  -e GCP_STORAGE_BUCKET=reader-cache \
  -e GCP_STORAGE_ACCESS_KEY=... \
  -e GCP_STORAGE_SECRET_KEY=... \
  ghcr.io/jina-ai/reader:oss

完整环境变量表请参阅 CONTRIBUTING.md。

本地开发

要求：

• nvm use
• Docker （可选 — 仅当你需要本地 MinIO 存储桶缓存时）

git clone git@github.com:jina-ai/reader.git
cd reader
npm install
# Optional, for bucket-cached mode:
docker compose up -d

然后在 VSCode 中按 F5 启动调试器，或在设置好相应环境变量后：

npm run dev

若要更深入地了解代码库 — 引擎、格式化配置、滥用缓解、部署拓扑等 — 请参阅 architecture.md。开发工作流、环境变量和测试请参阅 CONTRIBUTING.md。

许可资产

少量不可再分发的构件位于 licensed/，在构建/运行时需要：

• GeoLite2-City.mmdb 与 geolite2-asn.mmdb — MaxMind GeoLite 数据库（地理定位 + ASN 查询）。
• SourceHanSansSC-Regular.otf — Source Han Sans（用于 PDF/截图的 CJK 渲染）。
• gsa_useragents.txt — curl 引擎使用的 user-agent 列表。

一次性获取：

npm run assets:download

脚本（download-external-assets.sh）具有幂等性 — 会跳过已存在的文件，即使出现部分网络失败也会以退出码 0 结束。设置 FORCE_DOWNLOAD_EXTERNAL=1 可覆盖；若你自备副本，可设置 SKIP_DOWNLOAD_EXTERNAL=1 完全跳过。仓库的 CI 会内联获取相同 URL；此脚本仅为本地便利而设。

工作原理

某些网站遇到问题？

部分网站会抵制爬虫 — bot 挑战、地域封锁、过时的 CDN 边缘节点。可按大致递增的「这开始让我头疼」顺序尝试以下选项：

• 使用 API key。 匿名流量受到最严格的速率限制，且会落入最低信任池。经身份验证的请求可获得更高配额，并可使用内部代理等功能。前往 jina.ai/reader. 获取。
• 绕过缓存：使用 -H 'x-no-cache: true'。若陈旧或已被封禁的响应已被缓存，此操作可强制重新获取。
• 强制使用浏览器引擎：使用 -H 'x-engine: browser'。默认的 auto 引擎在可行时优先走轻量 curl 路径；部分网站仅向支持 JS 的浏览器提供真实内容。
• 通过 SaaS 代理路由：使用 -H 'x-proxy: auto'（需要 key）。Reader 托管的代理池会轮换住宅/数据中心 IP，并自动处理常见的反 bot 挑战。也可固定国家/地区，例如 x-proxy: us（参见地理与区域敏感爬取）。
• 自带代理：使用 -H 'x-proxy-url: <url>'。作为最后手段 — 当托管代理也无法穿透时 — 从第三方供应商（BrightData、Thordata、Oxylabs 等）购买住宅或 ISP 级代理，并直接传入 URL。支持 http、https、socks4、socks5；身份验证请使用 https://user:pass@host:port。

若以上均无效，请提交 issue，附上 URL 与你尝试过的 headers — 我们会排查。

许可证

Reader 由 Jina AI 提供支持，并根据 Apache-2.0 授权。