<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/jina-ai/reader) · [上游 README](https://github.com/jina-ai/reader/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Reader

[![codecov](https://codecov.io/gh/jina-ai/reader/branch/main/graph/badge.svg)](https://codecov.io/gh/jina-ai/reader)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jina-ai/reader)

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

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

请查看[在线演示](https://jina.ai/reader#demo)

或直接访问这些 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://jina.ai/reader#pricing)

<img width="973" alt="image" src="https://github.com/jina-ai/reader/assets/2041322/2067c7a2-c12e-4465-b107-9a16ca178d41">
<img width="973" alt="image" src="https://github.com/jina-ai/reader/assets/2041322/675ac203-f246-41c2-b094-76318240159f">

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

## 更新

- **2026-04** — 已将开源分支与 SaaS 代码重新同步。基于 MongoDB 的存储层已剥离；oss 分支开箱即可以无状态模式运行，并可通过 `docker compose` 可选启用 MinIO/S3 兼容的 bucket 缓存。参见[本地开发](#local-development)。
- **2025-12** — 存储层解耦，并支持二进制文件上传。PDF 及 MS Office 文档（Word、Excel、PowerPoint）现可直接通过 `file` 请求体字段 POST 上传——无需事先托管。参见 [cookbooks.md](./cookbooks.md#pdf-ms-office-and-raw-html-uploads)。
- **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 结果](https://r.jina.ai/https://www.nasa.gov/wp-content/uploads/2023/01/55583main_vision_space_exploration2.pdf) 与[原始文件](https://www.nasa.gov/wp-content/uploads/2023/01/55583main_vision_space_exploration2.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](https://r.jina.ai/https://en.wikipedia.org/wiki/Artificial_intelligence)

### [使用 `r.jina.ai` 抓取完整网站（Google Colab）](https://colab.research.google.com/drive/1uoBy6_7BhxqpFQ45vuhgDDDGwstaCt4P#scrollTo=5LQjzJiT9ewT)

### 使用 `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](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`，例如：

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

### [交互式代码片段构建器](https://jina.ai/reader#apiform)

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

<a href="https://jina.ai/reader#apiform"><img width="973" alt="image" src="https://github.com/jina-ai/reader/assets/2041322/a490fd3a-1c4c-4a3f-a95a-c481c2a8cc8f"></a>

### 使用请求头

你可以通过请求头控制 Reader API 的行为。下列列表涵盖最实用的选项——完整接口及最新默认值与校验规则，请参见 [https://r.jina.ai/docs](https://r.jina.ai/docs), 上的在线 API 文档，或 [`src/dto/crawler-options.ts`](./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 块。示例：

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

    ```markdown
    ---
    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](./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](./cookbooks.md#using-presets)。
  - `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](./src/dto/turndown-tweakable-options.ts)。

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

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

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

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

```bash
# 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 控制输出格式：

```bash
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 提供*足够*的线索，使其在推理、筛选和摘要中纳入这些图片：

```bash
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](./cookbooks.md)。每条目都是一个简短的 curl 示例，包含适用于该场景的 header 组合，以及一段说明权衡取舍的文字。

## 使用 Docker 自托管

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

```bash
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 端口：

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

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

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

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

### 带缓存运行

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

```bash
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](./CONTRIBUTING.md#environment-variables)。

## 本地开发

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

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

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

```bash
npm run dev
```

若要更深入地了解代码库 — 引擎、格式化配置、滥用缓解、部署拓扑等 — 请参阅 [architecture.md](./architecture.md)。开发工作流、环境变量和测试请参阅 [CONTRIBUTING.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 列表。

一次性获取：

```bash
npm run assets:download
```

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

## 工作原理
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jina-ai/reader)

## 某些网站遇到问题？

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

- **使用 API key。** 匿名流量受到最严格的速率限制，且会落入最低信任池。经身份验证的请求可获得更高配额，并可使用内部代理等功能。前往 [jina.ai/reader](https://jina.ai/reader#pricing). 获取。
- **绕过缓存**：使用 `-H 'x-no-cache: true'`。若陈旧或已被封禁的响应已被缓存，此操作可强制重新获取。
- **强制使用浏览器引擎**：使用 `-H 'x-engine: browser'`。默认的 `auto` 引擎在可行时优先走轻量 curl 路径；部分网站仅向支持 JS 的浏览器提供真实内容。
- **通过 SaaS 代理路由**：使用 `-H 'x-proxy: auto'`（需要 key）。Reader 托管的代理池会轮换住宅/数据中心 IP，并自动处理常见的反 bot 挑战。也可固定国家/地区，例如 `x-proxy: us`（参见[地理与区域敏感爬取](./cookbooks.md#geo--and-locale-sensitive-scraping)）。
- **自带代理**：使用 `-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](https://jina.ai) 提供支持，并根据 [Apache-2.0](./LICENSE) 授权。