> Source: https://clickhouse.github.io/loom/zh-CN/architecture/document-extraction/ (Markdown: https://clickhouse.github.io/loom/zh-CN/architecture/document-extraction.md)

<!-- i18n: source=docs/architecture/document-extraction.md blob=43e95a2510b1d98965d48e5a1b079a7c345a8d5c model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/architecture/document-extraction/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/document-extraction/), which is authoritative.

<a id="document-extraction"></a>

# 文档提取

上传的原始文件由提取器服务解析为一种统一的形态，即提取产物（extraction artifact）。提取器服务是一个独立的进程，拥有自己的依赖，绝不是 Loom 服务器本身。服务器把原始文件的字节发送到其格式所路由到的服务，将返回的产物视为不可信输入读回，并根据产物中的块切出结构化分块，因此一条 SQL 语句、一个 TOML 键和一个 Markdown 小节，都可以通过指向源文件的定位符被引用。Loom 自带一个参考提取器（`extractor/loom_extractor/`），支持 Markdown、HTML、纯文本、SQL、TOML、CSV、PDF、DOCX、PPTX、XLSX，并且在安装了 `pyarrow` 时支持 Parquet；运维人员也可以在同一份[线路契约](https://github.com/ClickHouse/loom/blob/main/docs/reference/extractor-contract.md)之下运行其他提取器。`knowledge.ingest` 以这种方式提取上传的原始文件（见[摄取](#ingestion)），文档源同步则对已注册文件夹中的 PDF、`.pptx` 和 `.docx` 文件调用提取器（见[同步文档源](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#syncing-a-source)）；`knowledge.add` 接收调用方已提取好的文本。

<a id="the-service-boundary"></a>

## 服务边界

| 一侧              | 职责                                                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Loom server       | 契约（`server/knowledge/domain/extract/`）、对提取器返回内容的检查、格式路由、结构化分块器以及客户端（`server/knowledge/app/extractors.py`） |
| 提取器服务 | 格式检测、严格解码和所有解析器；不持有 Loom 令牌、数据库凭据，也不访问 bucket：它接收字节并返回 JSON                                           |

解析文件意味着对上传者可控的输入运行解析器。把这一步放在服务器进程之外，可以让解析器缺陷、病态输入或解析器的依赖项远离持有 ClickHouse 凭据、签名密钥和租户数据的进程，也让运维人员可以为某种格式换上自己的工具。`tests/unit/test_package_contracts.py` 会检查没有任何服务器模块导入提取器、sqlglot 或 pypdf，并且知识平面不导入任何解析库。

**路由。** 服务器根据调用方的说明确定格式（先看声明的格式，其次是文件扩展名，再次是媒体类型，最后是 `text`），不读取字节，并把原始文件发送到 `LOOM_DOCUMENT_EXTRACTORS_JSON` 为该格式指定的服务；当媒体类型指向该格式时，则发送到为该媒体类型指定的服务；否则发送到 `LOOM_DOCUMENT_EXTRACTOR_URL`。只有当该服务的 `/v1/capabilities` 声明了某种格式时，才会提取该格式；声明会在一分钟后重新读取。名称为 `.doc`、`.xls` 或 `.ppt` 的文件在任何调用之前就会被拒绝。路由键是格式名称或指向某种格式的媒体类型，匹配时忽略其参数和大小写；其他任何键都会在加载设置时被拒绝。部署对外宣告的内容就是这些声明所说的：当该格式的文件可以发往的某个服务声明了它时，`knowledge.formats` 将该格式报告为可用；当该服务无法读取时，则报告为未知（仅由某个媒体类型的路由提供服务的格式，会在上传携带该媒体类型时读取）。它会在 5 秒内并行读取各个服务；某个服务在 5 秒内无法读取时，其格式最长一分钟内为未知，直到对它的一次 capabilities 读取成功。

**失败即关闭。** 以下情况都会抛出 `ExtractorUnavailable`，该来源可以重试：格式没有配置服务，服务没有声明该格式，服务不可达，整个调用耗时超过 `LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S`，服务拒绝服务器的令牌（`401`、`403`、`407`），返回 `408`、`429`、`format_unavailable`、`5xx`，或任何既不是 `200` 也不是 `4xx` 的响应（重定向、`204`）。服务拒绝某个来源时，会抛出带有契约错误码（`format_mismatch`、`encoding`、`too_large`、`timeout`、`resource_limit` 等）的 `ExtractionFailed`；违反契约的响应（`invalid_artifact`）也是如此。没有进程内的回退方案：未配置提取器时，不会提取任何原始文件。

**令牌。** 服务器向每个服务发送 `LOOM_DOCUMENT_EXTRACTOR_TOKENS_JSON` 中为其 URL 保存的令牌，没有则使用 `LOOM_DOCUMENT_EXTRACTOR_TOKEN`，因此运维人员自己的服务无需持有参考提取器所接受的令牌。

**不可信的输出。** 服务器请求未压缩的响应（`Accept-Encoding: identity`），把压缩的响应视为服务不可用，并读取不超过 `LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES` 的产物，更长的产物按 `resource_limit` 拒绝。随后，在分块、嵌入或发布任何内容之前，`parse_artifact` 会对其进行检查：schema 版本、所请求的格式、每个块的类型、唯一的 id 以及指向更早块的父级；每个块最多 10,000 个键（每个键 1,024 个字符）和 64 个章节路径条目（每个条目 500 个字符）（因此从长块切出的各个分块共享其键，每个分块的工作量保持线性）；locator 的区间是范围；覆盖计数不超过其总数；字符串是有效的 Unicode；数字是 JSON 数字（没有 `NaN` 或 `Infinity`；有符号 64 位整数（-2^63 到 2^63-1），其他数字在 double 范围内）；每个表的形状（唯一的 id、最多 16,384 个带类型的列，列名最多 500 个字符，行与列数一样长，由标量或单元格错误组成，工作表和行是 locator）；以及 `attrs` 和 `options` 的嵌套深度（16；参考 TOML 解析器会省略嵌套深于 8 的值的 `attrs.value`，其文本仍保留在块中）。`complete` 由计数、失败和丢失重新计算，标志与之不符的产物会被拒绝。契约中未列出的字段会被丢弃。服务器按其自身序列化结果的 SHA-256 来定位产物，而不是按服务返回的字节。

**参考提取器中的隔离。** 每个 `/v1` 调用都携带 `Authorization: Bearer <token>`；服务在没有至少 16 个字符的令牌时拒绝启动。每次提取都在子进程中运行，并且在子进程读取来源之前：

| 子进程                                | 方式                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 没有环境变量                       | 仅以 `PYTHONPATH`、`PATH` 和 `LC_ALL` 启动，因此令牌不在其中                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 不能读取服务或其他子进程 | 服务和每个子进程都设为不可转储（`PR_SET_DUMPABLE`），因此同一用户的进程无法通过 `/proc` 或 ptrace 读取它们的环境、内存或打开的文件                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 资源有限                    | 地址空间（`LOOM_EXTRACTOR_MEMORY_MB`）、CPU 秒数、文件大小为 0（可以创建空文件，但不能写入），无 core dump                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 不启动进程                       | `RLIMIT_NPROC` 为 0，因此解析器启动的任何东西都不会在提取结束后继续存活；在超时、断开连接或取消时仍在运行的子进程，会在释放其槽位之前连同其进程组一起被杀死                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 不打开套接字                       | 在 no-new-privileges 之后设置的 seccomp 过滤器使 `socket`、`socketpair` 和 `io_uring_setup` 以 EPERM 失败，`ptrace`、`process_vm_readv`、`process_vm_writev` 和 `pidfd_getfd` 同样如此（x86_64 和 aarch64；在其他架构上服务拒绝启动），因此它无法访问任何地址，包括其网络上的 Loom server。并发的同级进程在变为不可转储之前，仍可通过 `/proc/<pid>/mem` 写入，因此当 `LOOM_EXTRACTOR_CONCURRENCY` 大于 1 时，被接管的子进程仍可能在某个同级进程给自己加上过滤器之前对其打补丁 |
| 执行时不获得权限              | 服务和每个子进程中都设置 `PR_SET_NO_NEW_PRIVS`，因此没有 setuid 二进制文件或文件能力可以提升权限                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 只加载该软件包                   | 在 `/` 下以 `-P` 运行，因此当前目录或脚本目录都不在 `sys.path` 上；该软件包及其依赖项以只读方式安装给服务的用户，因为 `sys.path` 上属于它自己的文件可能改变之后每个子进程导入的内容                                                                                                                                                                                                                                                                                                                                                                                                         |
| 看不到请求                         | 其命令行只包含它的限制；文件名和选项通过 stdin 传入                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

服务会在墙钟超时、调用方断开连接或其输出超过产物上限时杀死子进程，并且只有在其 `LOOM_EXTRACTOR_CONCURRENCY` 个槽位之一空闲时才读取来源，因此该上限也涵盖了内存中持有的原始文件。槽位默认为一个：子进程从启动起到把自己设为不可转储之前，可被其用户的其他进程读取，因此被恶意来源接管的子进程可能在那一刻打开并发子进程的来源。请通过增加服务副本而不是槽位来扩展。内核不会让 root，或拥有 `CAP_SYS_RESOURCE` 或 `CAP_SYS_ADMIN` 的进程受进程数限制约束，因此服务在以 root 身份或被允许持有这两种能力之一的情况下拒绝启动。子进程在其进程内并不会被禁止读取文件系统：禁止这些读取的是它所运行的容器。服务在其套接字过滤器未覆盖的架构上拒绝启动。设置见 [`extractor/README.md`](https://github.com/ClickHouse/loom/blob/main/extractor/README.md)。

<a id="the-artifact"></a>

## 产物

| 部分       | 内容                                                                                                                                                                                                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blocks`   | 按顺序排列的来源结构：`heading`、`paragraph`、`list`、`code`、`sql_statement`、`toml_table`、`toml_key` 等；每个块都带有文本、定位信息、章节路径和父块                                                                                                                                                  |
| `tables`   | 来源中包含的表格：每个表格有名称、带类型的列、各行的值、表头行数和定位信息（CSV、XLSX、PDF、Parquet）                                                                                                                                                                                                   |
| `coverage` | 该格式的组成单位（`lines`、`statements`、`keys`、`chars`、`pages`、`paragraphs`、`slides`、`rows`）、单位总数、已提取的数量、每个失败单位及其原因，以及每项丢失的能力                                                                                                                                    |
| `warnings` | 读者应当看到的事实，例如 SQL 方言存在歧义                                                                                                                                                                                                                                                               |
| `options`  | 解析时使用的覆盖选项（`sql_dialect` 仅用于 SQL，`encoding` 使用其编解码器名称）                                                                                                                                                                                                                         |
| `attrs`    | 格式相关的事实（`dialect`、`dialect_source`、`dialect_candidates`；HTML 页面或 PDF 的 `title`；PDF 的 `pages` 和 `furniture`，演示文稿的 `slides`，工作簿的 `sheets`；`images_unread`，即其中的图片、图表、示意图或嵌入对象未被读取的文本所在的 PDF 页面或 PPTX 幻灯片）                                  |

块的 `id` 为 `b<ordinal>`，在其产物内保持稳定。`keys` 是读者查找该块所用的确切名称：SQL 语句创建、写入和读取的对象及其列（对于 sqlglot 无法解析的语句，则是其 token 包含的所有名称），每个限定名称也以其最后一部分出现（`analytics.events` 对应 `events`），并去掉引号（``db.`my.table` `` 对应 `my.table`；带引号的部分保留其中的点）；TOML 表或键的完整路径及其不含索引的形式。

定位信息只设置适用的字段：所有文本格式都有 `line_start`/`line_end`（从 1 开始）；Markdown、纯文本、SQL 以及无效 TOML 文件的文本块有 `char_start`/`char_end`（解码后文本中的偏移量）；TOML 有 `key_path`；PDF 的页面和 PPTX 演示文稿的幻灯片有 `page_start`/`page_end`（从 1 开始）；工作簿的工作表和 CSV 文件的行有 `sheet` 和 `row_start`/`row_end`（计入表头），PDF 表格的行则连同其页面一起给出。DOCX 本身没有页面（分页由渲染器决定），因此其块不带定位信息，引用时使用其章节路径。Markdown 标题的范围涵盖其源码所在的一行或多行（包括标记），而其文本是清理后的标题，因此长标题的某个窗口引用的是该标题的整个范围。由多个块切出的分块会跨越这些块的行、字符、页面和行，并且当这些块都指向同一个工作表时保留该工作表。

产物被序列化为排序后的紧凑 JSON，并带有 `schema_version`，以这些字节的 SHA-256 作为其地址。解析器或选项的变化会针对同一来源修订版生成新的产物；产物从不被编辑。读取方会拒绝其不认识的 `schema_version`。`parser_version` 指明一次解析所依赖的版本：SQL 为 sqlglot 的版本，PDF 为 pypdf 的版本（当 OCR 读取了某一页或某张幻灯片时还包括 Tesseract 的版本），HTML、TOML、CSV 和 XLSX 则为 Python 版本，因为它们的解析器随 Python 一起提供（`csv` 及其 sniffer；用于以文本形式写入的 XLSX 日期的 `datetime.fromisoformat`）。

<a id="formats-in-the-reference-extractor"></a>

## 参考提取器支持的格式

PDF、DOCX 和 PPTX 读取器对文档的文本、标题、表格和页面的保留程度，与基于版面模型的基线相比如何，见[文档解析结果](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md#document-parsing)。

`detect_format` 先读取字节内容，再看文件名。PDF、DOCX、PPTX 或 XLSX 容器（依据 zip 内的部件）以及 Parquet 文件按内容识别；文件名声称的格式与字节内容不符时会被拒绝（`format_mismatch`），旧版二进制 Office 文件会被拒绝（`unsupported_format`），名为 `.doc`、`.xls` 或 `.ppt` 的文件也一样，除非声明了格式。文本按严格模式解码：根据字节顺序标记识别 UTF-8、UTF-16 或 UTF-32，或使用声明的编码；文本为 UTF-8 时，无论是否声明，UTF-8 字节顺序标记都会被丢弃，声明的字节序编码（`utf-16-le`）的标记也同样丢弃。无法解码的字节会产生 `encoding` 失败，并指出其偏移量；未声明的 UTF-8 文本中出现 NUL 字节（无论其前是否有字节顺序标记）则视为二进制；二者都不会被替换后再建立索引。

| 格式 | 解析器 | 块 |
| ---------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Markdown | 遵循 CommonMark 标题、围栏和 HTML 块规则的块解析器 | 标题、段落、列表、围栏代码、front matter |
| 纯文本 | 段落分割器 | 每段连续的非空行为一个段落（以 `#` 开头的行是文本，不是标题） |
| HTML | 标准库的解析器 | 标题、段落、列表项、表格、引用、定义、`pre` |
| SQL | `sqlglot`，从不执行 | 每条语句一个块 |
| TOML | `tomllib` 和行扫描器 | 每个表头和每个键各一个块 |
| PDF | `pypdf`：其文本片段的位置和绘制的线条；OCR | 按页：标题、段落、列表、代码、表格；页眉页脚等版面装饰被排除 |
| DOCX | 标准库的 zip 和 XML 读取器 | 标题、段落、列表、表格、脚注和尾注 |
| PPTX | 标准库的 zip 和 XML 读取器 | 按幻灯片：标题作为标题块、每个文本形状、表格、演讲者备注 |
| CSV | 标准库的 `csv` | 一个表格；其行以最多 20 行为一块 |
| XLSX | 标准库的 zip 和 XML 读取器 | 按工作表：一个表格、以名称作为标题、其行以最多 20 行为一块 |
| Parquet | `pyarrow`，从内存中的字节读取 | 一个表格；其行以最多 20 行为一块 |

**Markdown。** 标题包括 ATX 标题、setext 标题和单行 `<hN>`。位于 setext 下划线之上的段落（下划线缩进至多三个空格）是一个标题；位于 `---` 之上的列表项、引用或分隔线则不是。围栏块保留其正文的各行而不含围栏；围栏以一串同样字符且长度不小于起始围栏的单独一行关闭，其语言为信息字符串的第一个词，其余部分保留为 `info`（空块也保留）。在段落内部，只有项目符号或编号为 1 的项才会开始一个列表，因此以 `2019.` 开头的折行仍是正文。分隔线（`***`、`- - -`）属于标记：它会结束其上方的段落或列表，且不属于任何块的文本。HTML 块按原样作为一个段落块，且永远不是标题的标题文字（CommonMark 的起始条件）：以注释、`<?`、`<![CDATA[`、`<!`（`<!DOCTYPE html>`）或原始文本标签（`<pre>`、`<script>`、`<style>`、`<textarea>`）开头的块，在包含其结束标记（`-->`、`</pre>`）的那一行结束，因此其后一行可以是 setext 标题；以块级标签（`<p align="center">`、`<div>`）开头或仅由标签构成的行（`</div>`）开头的块，在空行处结束。除仅含标签的行外，其余都会结束其上方的段落；段落内部仅含标签的行是该段落的文本。空的 ATX 标题（`# #`）属于标记，会结束其上方的段落；而标题文字清理后为空的标题（`# <img src="logo.svg">`）仍是一个段落。开头的 YAML front matter（位于 `---` 标记之间的 `key:` 行，行首的 `#` 后跟空白时是标题而不是注释）是一个块。块带有行和字符跨度，覆盖率统计非空行，每一行要么落在某个块中，要么是围栏或 front matter 的分隔符、分隔线或空的 ATX 标题（根据块的跨度统计，用于防范解析器改动导致丢行）。

这些规则是提取器自己的（`extractor/loom_extractor/markdown.py`）。`knowledge.add` 的标题分割器用于对调用方已提取的文本分节，它有自己的规则，对同一文档的分节结果可能不同。

标题的标题文字最多取前 500 个字符进入其下各节的节路径，截断会按下文的契约边界所述加以标记；标题块保留全部内容，并像任何比分块更长的块一样进行窗口切分。

**HTML。** `blockquote`、`dd` 和 `dt` 是段落；开启一个列表项的 `<p>` 及其后的 `<p>` 都是该列表项的文本。结束标签被省略的块，会在下一个块、其容器的结束处或文档结尾处关闭（块内的容器会使其保持打开；`br`、`hr` 和容器的开始会分隔单词），未关闭的 `head` 在第一个 body 元素或文本处关闭。块的行跨度从其第一行文本到最后一行文本。`script`、`style`、`template`、`noscript`、`svg`、`title` 和 `head` 不进入块（`<title>` 的文本是 artifact 的 `attrs.title`）；覆盖率统计这些元素之外的可见字符，以及块中包含了多少个（连接表格单元格的竖线除外），这是同类的防护。两者都不统计块内部自身丢失的内容，例如被去除的行内标签。未关闭的隐藏元素会隐藏文档的其余部分；其中的文本被计为未读取，并给出指明这些未关闭元素的失败。

**HTML 表格。** 一个 `<table>` 是一个块，每行一行文本，单元格以竖线连接，`attrs.table` 记录其 `rows` 和 `columns`，与 DOCX 表格相同，只是没有文本的行会被丢弃。行结束之后的单元格开始下一行，行组的开始或结束（`thead`、`tbody`、`tfoot`）会结束当前打开的行。它的标题（caption，连同其中的任何标题或列表）以及不在任何单元格中的文本（行与行之间）按原顺序作为表格之前的段落，就像浏览器把它们分开显示一样；caption 内的表格与其中的标题或列表一样，被当作 caption 的文本读取。

单元格按 HTML 的方式放入各列：跨度（`colspan`、`rowspan`）按 HTML 读取非负整数的方式读取，被 `rowspan` 向下延续的单元格，在其下各行中占据其所在的列，表现为空单元格，直到其行组结束。仅由空单元格和跨多列的单元格填充的列是间隔列，会被丢弃，除非有文本的单元格被延续到该列中。放置时统计每行的单元格以及延续到该行的单元格；超过一百万个这类单元格的表格会保留每一个单元格。只剩一列的表格不含网格：其各行是一个没有 `attrs.table` 的段落，与用表格包裹整个页面（如电子邮件）的情形相同。

如果表格的单元格中包含标题、列表、`pre`、表格或第二个段落，则它是用于排版页面的（如电子邮件、用表格单元格排版的页面）：其单元格、caption 以及不在单元格中的文本，按顺序作为其中包含的块读取，其中嵌套的表格仍是表格。不在任何单元格中的标题、列表、列表项、定义、`pre` 或表格会结束该表格（无论其 `</table>` 是否省略），其后的行作为段落读取，因此未关闭的表格不会吞掉页面的其余部分。表格所处元素的结束不是表格的结束，因为 HTML 将表格视为自己的作用域：不在单元格中的后续内容会像浏览器显示的那样显示在表格之前，未关闭的 caption 会包含它。不在单元格中的每个段落或容器的文本各自独立。

**SQL 语句。** 语句按方言的词法单元分割，因此字符串或注释中的 `;` 不会结束语句。客户端自己的命令行（`GO`、单独的 `/`、`DELIMITER ;;`、反斜杠命令）不是 SQL：包含它们的脚本仍按其 `;` 词法单元分割，被命令行连在一起的语句是一个 `UNKNOWN` 块，覆盖率将其记为失败。由客户端整体发送的主体（存储过程的 `BEGIN … END`）会在其内部的 `;` 处切开：头部保留 `CREATE` 及其名称，主体的每条语句各自成块，各有自己的读和写，结尾片段（`END`）是 `UNKNOWN`；没有 `BEGIN … END` 的 T-SQL 主体可能被读作完整。不按客户端自己的规则分割；请声明方言，并预期此类脚本会报告丢失 `sql_structure`。其块记录语句的种类（`CREATE MATERIALIZED VIEW` 与 `CREATE VIEW` 不同）、创建的对象、写入的对象（视图的 `TO` 表、索引所建在的表、`DROP` 或 `TRUNCATE` 所移除的对象、`MERGE` 的目标）、读取的表（CTE 不算）、其列及其注释（同一行中 `;` 之后的注释属于该语句）。覆盖率统计语句而非仅含注释的块，并以块 id 指明失败的语句。

**SQL 方言。** 声明的方言仅凭其名称按原样使用；未知的方言，或逗号后带有 sqlglot 设置的方言，会返回 `invalid_option`。否则每个候选方言都会读取脚本的一个窗口：脚本不超过 50,000 个字符时是整个脚本，否则是前 50,000 个字符内截至第 50 个 `;` 的前缀，当其词法分析器拒绝该前缀时（截断点可能落在带引号的主体内部）则取更短的前缀。能对更长窗口完成词法分析的方言排名在前，因此拒绝该脚本的方言不会因对其更短截段的解析而获胜；然后，其前 50 条语句的文本中成功转成语法树的比例更大者胜出（用比例，这样把带引号的主体拆成许多小语句的方言不会获胜），平局时按固定顺序取第一个（ClickHouse 排第一）。能解析出内容的方言之间的平局会以 `sql_dialect_ambiguous` 报告，并列出平局的候选；脚本使用其中第一个能完整读取它的词法分析器所属的方言来分割；当读取脚本最多的那些方言都解析不出任何内容时，使用其中第一个，并设 `dialect_source = "default"`，且没有候选。检测每个窗口最多读取 50,000 个字符，每种方言最多约七个窗口，因此第一条语句更长、或第一个带引号的主体超出每个截断点的脚本，可能被错误检测：请声明其方言。所选方言无法转成语法树的语句仍是 `UNKNOWN` 类型的可搜索块，列在 `coverage.failed` 中，并设置 `coverage.lost = ["sql_structure"]`；词法分析器无法分割的脚本就是这样一个块。

**TOML。** `tomllib` 决定有效性、类型和值；旁边的扫描器找出行、注释和原始的值文本，包括跨多行的值（多行字符串、数组、内联表）。键块的文本是 `<full path> = <value text>` 加上其注释，写成可独立阅读的形式；其行跨度指向源文件。表或键上方的注释进入其文本和行跨度；后面没有表或键的一串注释是独立的段落，多行数组内部的注释保留在该键的文本中。无效的文件（包括含有超出有符号 64 位整数的文件）会保留为段落块，并设置 `coverage.lost = ["toml_types"]` 及原因，原因在可能时指明行号或键路径。键的 `attrs.value` 是其 JSON 值，但日期或时间取其 ISO 文本，无穷大或 NaN 浮点数取其文本（`inf`、`nan`），无论其 `value_type` 是什么。

**PDF。** 页面按其版面读取，依据 pypdf 报告的每个所显示文本片段的位置和所绘制的线条（`extractor/loom_extractor/pdflayout.py`）。片段的宽度来自其字体的宽度（`/Widths`，或 CID 字体经 ToUnicode 映射的 `/W`，或标准字体的度量），不含文本状态的字符间距、单词间距或水平缩放；一个文本操作符的片段（在字体变化处被切开，例如来自另一种字体的连字）从其前一片段的末尾继续。位于同一基线上的片段构成一行，在间隙超过字号处切成若干段；如果由几何关系放在一起的两个片段所构成的单词不在页面的文本层中，而它的两个部分都在，则将它们分开；原位绘制两次的片段（伪粗体、阴影）只读取一次。页面会被旋转，使大多数文本片段的方向变为从左到右，因此横向显示的页面（`/Rotate`，或内容被旋转绘制）与其他页面一样读取；方向不同的文本保留为各自独立的行，每行一个段落，位于该页自己的内容之后（`attrs.orientation`）。然后依次处理：

- 页面中间有一条至多二十分之一的行穿过的通道，且两侧的文本都填满其所在的栏时，页面被分成两栏，在通栏行之间先读左栏再读右栏；
- 相交的水平线和垂直线构成的网格（描边线或细的填充框，包括表单 XObject）是带线表格，其单元格是每个框内的文本，空行和空列被丢弃；围着文本的一个框不是表格；
- 一串被切成段、且位于页面两个或更多区带中的行是无边框表格：第一个区带中有文本的行开启一行，没有的则并入上一行的单元格（单元格内折行）；与其列表项文本分开放置的列表标记（`•`、`1.`、符号字体的项目符号）不是一列；
- 页面装饰（版面装饰）：不被任何表格作为行包含、位于页面顶部或底部十分之一、含有字母、且其文本（数字除外）在至少两页且至少五分之二的页面的同一位置重复出现的行，或者单独的页码，都不进入块（无边框表格两端的候选行，除非是单独的页码，只有在它填满每一列时才算该表格的一行，如表格自己的表头在每页顶部重复；或者在距表格行间距的一倍半之内开启一行；或者在顶部时填满除第一列之外的每一列，即位于一列行名之上的表头；因此上方的页眉、下方的页码，以及带有跨两列单元格的重复表头都不算）；artifact 会列出每一种装饰（页码变化的页脚算作一种），附上其第一段文本和出现的页数（`attrs.furniture`，前 200 种），并发出已这样处理的警告；
- 其余的是段落（同一样式的行，在间隙比该字号下文档最常见行距大出 30% 以上处分开）、列表项（以标记开头）和代码（等宽字体，保留缩进），以及标题：不超过三行、二十个词的段落（读作列表项的编号段落则限一行），字号比正文（字符最多的字号）至少大 12%，或为粗体且字号达到该字号的 95% 或更大，并且除非有编号，否则不以句子的方式结尾。字号越大排名越高；在同一样式内，编号（`2.1`）决定层级。

当 PDF 有大纲（书签）时，大纲条目就是标题：每个条目按大纲顺序，取上一个标题之后第一个包含其标题文字的行（或文本即其标题文字的段落），其所在段落围绕它被拆开；若没有任何行匹配，则紧跟在上一个标题之后；字号比所有大纲标题都大的标题（大纲中未列出的文档标题）保留在它们之上，大纲的各层级在每一页上都位于它之下。如果一个表格的行在下一页顶部以相同的列继续，则它是一个表格，跨越其延续的所有页面，下一页重复的表头行被丢弃。

表格与表格类来源的表格相同（见下文**表格**）：`tables` 中带类型的表格，其第一行是表头，其定位符是其页码和行号（表头是第 1 行），其行是由 `column: value` 行组成的块，引用其所含的页和行，因此命中结果会引用其行，数据集会保存其值。只有当单元格的值读回后与页面显示的一致时，才像 CSV 字段那样为其确定类型，因此 `1.50` 和版本号 `1.10` 仍是文本。当页面按版面读取得到的字母和数字少于其文本层的 99.8%（不计空白和大小写），或其行数超过 5,000，或其版面无法读取时，该页改为按其文本层读取（文本在空行处分开，大纲标题位于包含其标题文字的行），并附带指明该页及原因的警告，因此读取版面出错时绝不会丢失文本。没有文本但绘制了图像（图像对象，或表单中的图像）的页面，在提取器具备 OCR 时用 OCR 读取（见下文），否则是失败单元：其文本需要 OCR，因此含这种页的 PDF 不完整，只有使用 `allow_partial` 才会发布；内联绘制的图像（在页面内容或表单中）不会被读取，这样的页面是说明此情况的失败单元（有文本、且内联图片覆盖其五分之一而自身文本没有填满它的页面是部分的，没有文本、且内联图像旁边有 OCR 所读图片的页面也是部分的；宽度不足一点的内联图像视为没有）。有文本的页面，若其绘制或版面无法读取，或引用了文件中不存在的图像对象，或绘制了嵌套在四层其他表单内（超过读取器遍历的深度）的表单，则当它可能绘制了图片时是部分的；没有文本且处于该状态的页面是失败单元，绝不会使整个文件失败。页面在其资源中包含但从未绘制的图像视为没有。有文本、且绘制了覆盖页面五分之一或更多的图片（截图、白板照片）的页面，其图片用 OCR 读取，每一行是一个独立的段落块，位于该页文本之后（`attrs.ocr`），绝不会是表格或标题；若没有 OCR，则不完整：页面被读取，并有一个失败单元说明图片中的文本需要 OCR。页面自己的文本已占其十分之一的图片（扫描件的文本层，绘制在其图像之上）不再重复读取。有文本、且绘制了较小图片（OCR 不读取：宽或高不足一点的视为没有，页面自己的文本已填满的也不读）的页面，读取其文本，并在 `attrs.images_unread`（其页码）和该文件的一条警告中指明：只绘制在这类图像内部的文本不会被提取；因图片而成为部分的页面，改由其原因来命名，该原因指明是什么使其停止，而不是列出其包含的每张图片。pypdf 无法读取的页面是失败单元，而不是整个文件；失败页面的大纲标题仍会开启其各节。字体映射没有给出 Unicode 字符的字符（孤立代理项）读作 U+FFFD，并附带指明其页面的警告。只有输入密码才能打开的 PDF 返回 `unsupported_format`。

**OCR。** 提取器镜像安装了 Tesseract 和 Leptonica 的库以及 Tesseract 的英文模型（`LOOM_EXTRACTOR_OCR_LANGUAGES` 指定镜像中包含的其他语言；缺少某个语言时服务拒绝启动，库未安装时会提示一次）；提取子进程通过 ctypes 在自己的进程中加载它们（`extractor/loom_extractor/ocr.py`），因为它不得启动任何程序，OpenMP 被限制为一个线程，并在读取第一张图片时加载。使用 `OCR=off` 构建，或设置 `LOOM_EXTRACTOR_OCR=off`，则不读取任何图像，上述规则说明了此时哪些内容不完整。PDF 图像按其所含文件读取（JPEG、JPEG 2000、CCITT 传真，pypdf 将其包装为 TIFF），或按其原始采样读取（灰度、RGB、按黑色通道的 CMYK，或灰度或 RGB 的索引，1 位或 8 位）并作为 PNM；JBIG2 只有单独的程序才能解码，因此不读取，并会说明这一点。图像最多 40 M 像素（解码后或缩放后），其尺寸在解码之前从其自身的头部读取（GIF 通过遍历其块来读取其屏幕和每一帧，因为每一帧按各自的尺寸解码），显示宽度不足一点的 PDF 图像（占位图、跟踪像素）不读取，因为其中没有文本；显示分辨率低于每英寸 200 像素的图像先缩放到约 300。图像按灰度读取，Tesseract 自行设定阈值；大部分为深色的图像（深色屏幕上的浅色文字）会被反转成浅色后读取。在读取单词之前，长度超过横向半英寸或纵向三分之一英寸的笔画（带线表格的网格；横向至多 300 像素、纵向至多 210 像素，按每英寸 600 像素计，因此比这更高的字母，在每英寸 300 像素下约 36 点或每英寸 1,200 像素下 18 点，会连同它们一起失去竖笔画；比十分之一英寸更粗的深色区域（如标题的背景）不是笔画，紧挨着它、距离在同样范围内的笔画（接触深色表头行的线）或其中所含浅色字母之间的间隙也不是）会被从图像中涂掉（所用尺寸至多是每英寸 600 像素时的尺寸，因此精细显示的截图按其自身尺寸读取，清理开销仍然很小），并成为该页带线表格的线条，因为 Tesseract 会把带线表格的单元格当作一幅图片来读；紧挨这种线条的单词会丢掉其边缘残留的一笔（`[Owner`、`rota-8|`），仅由竖线构成的单词会被丢弃（一条淡得无法被找到的网格线），其他单词按原样读取（`timeout = 30`、`__init__`）。每个单词落在图像被绘制所在的页面上，其点数大小由 Tesseract 根据其行的 x 高度读出，该值是它在每英寸 300 像素下读取时给出的，并被换算为图像显示时的大小（标题由此得出，步长为 8% 而不是 12%，因为 OCR 读取整数点数；而小于 6 点的字号（OCR 在精细显示的图像中会得出这样的字号）按十分之一点而非半点比较），因此上述版面读取会把扫描页变成段落、标题和表格，其块标记为 `attrs.ocr`。一个文件最多读取 `LOOM_EXTRACTOR_OCR_MAX_IMAGES`（30）张图像，每张图像无论被多少页或幻灯片显示都只读一次，一页上用 OCR 读取的图片中最多 50 张，单张图像的识别最多 20 秒；图像超出其中任何一项限制、绘制过大以致无法收集每张图片，或 OCR 无法读取的页面是部分的（若自身没有文本则是失败单元），并说明原因。artifact 列出用 OCR 读取的页面（`attrs.ocr_pages`；演示文稿的是 `attrs.ocr_slides`），当读取过图像时，`parser_version` 会写明 Tesseract 的版本。OCR 引擎使镜像增加约 44 MB（压缩后 12.5 MB）。OCR 读取的是图像中以文本形式显示的内容，而不是图表或示意图的结构。

**DOCX 和 PPTX。** 两者都是由 XML 部件组成的 zip，用标准库读取：处理恶意文件时不运行任何第三方 XML 或图像库。部件必须是存储或 deflate 压缩（OOXML 所写的方法），且声明的解压后大小至多 256 MiB，包内所有部件合计至多 512 MiB；部件只解压到其声明的大小，因此 zip 炸弹会在此停止。声明了 DOCTYPE 的部件（任何编码）会被拒绝，因此不会展开任何实体。无法读取的部件（损坏、超出限制、不是 XML、编码为 XML 解析器不能读取的编码）会使其所属的单元失败：幻灯片、幻灯片的备注、样式、脚注；文档部件本身失败则使文件以 `corrupt` 失败。DOCX 标题是样式为 `Heading N` 或 `Title` 的段落，或自身或沿其样式的 `basedOn` 链带有大纲级别的段落，以最近设置的那个为准（级别 9 是正文，无论样式如何都不是标题）；一旦某个 `Title` 段落被读作标题，它的深度为 1（无论它带有什么大纲级别），其后所有其他标题都在自身级别之下再深一级（`Heading 1` 为深度 2），这样各节位于标题之下，后面再出现的标题深度又为 1；编号段落或 `List` 样式的段落是列表项，一连串这样的段落是一个列表块。插入的文本会被读取，被跟踪的删除（其中的片段、行和单元格）以及在原位置的被移动文本则不读取；内容控件或自定义 XML 元素的文本在原位读取，在正文、表格的行及其单元格中皆如此，备用内容（alternate-content）的选择项只读一次。页眉、页脚和批注不属于正文，不会被读取；脚注和尾注跟在正文之后（`attrs.note`）。嵌入的文档（`altChunk`）是失败单元，只有图片、图表、示意图或嵌入对象而没有文本的文档也是失败单元。文本文档在其正文、表格或注释中包含绘图所展示而读取器不读取的内容时会发出警告：图像（在图片、组或形状填充中，VML 形状的图片填充，或备用内容的回退项，其中不认识的绘图，如 3D 模型，保留其图片；其中绘制的文本属于该选择项，会被读取）、绘制的文本（艺术字、锁定画布的文本）、图表、示意图或嵌入对象；页面背景不读取，也不指名。被跟踪的删除不会计入，文本框（其文本会被读取）、线条或普通形状不会发出警告。PPTX 演示文稿按其幻灯片顺序读取（演示文稿的幻灯片列表，而不是部件的名称）：幻灯片的标题是一个标题，其他块位于其下；每个文本形状（成组的形状在原位，备用内容中的形状取其第一个选择项）是一个块，演讲者备注是一个标记为 `attrs.notes` 的块；隐藏的幻灯片（`show` 为 false）会被读取并标记为 `attrs.hidden`。覆盖其幻灯片五分之一或更多的图片用 OCR 读成一个标记为 `attrs.ocr` 的段落块，位于该幻灯片的各形状之后（多张幻灯片显示的同一图像只读一次，图片的解压有其自己的限制，与包内部件的限制分开），而没有 OCR，或图片是链接而不是保存在文件中时，该幻灯片是说明原因的失败单元。图片的尺寸取其自身的尺寸，按其所在的每个组缩放，否则取其在幻灯片版式（先按索引，再按类型）、然后母版中的占位符的尺寸；任何地方都没有给出时，取幻灯片的尺寸，没有声明幻灯片尺寸的演示文稿使用默认的 10 乘 7.5 英寸。幻灯片所展示的内容全部由图片、图表、示意图或嵌入对象承载、没有文本时是失败单元，除非 OCR 读取了其图片；其唯一文本来自 OCR 的幻灯片，在含有图表、示意图或嵌入对象时也是失败单元。幻灯片 id 的关系没有指向任何幻灯片部件、幻灯片嵌套得比读取器遍历的更深，以及幻灯片的关系无法读取、或其图片的尺寸取自无法读取的版式或母版的占位符时（其文本仍会读取），也是如此。含文本的幻灯片中有 OCR 不读取的图片（小于幻灯片五分之一的图片、以图片填充的形状、组或表格单元格、作为幻灯片自身背景的图片，或读取器不认识的绘图（如墨迹）或公式的回退图片，其数学内容不读取；其版式、母版或主题提供的背景不读取），或有图表、示意图或嵌入对象时，读取其文本，并在 `attrs.images_unread`（其幻灯片编号）和该文件的一条警告中指明，除非该幻灯片因其所展示的内容而失败：其失败说明是什么使其停止，而不是列出其包含的全部内容。两种格式中的表格都是一个块，每行一行文本，单元格以竖线连接，`attrs.table` 记录其 `rows` 和 `columns`。

**表格（CSV、XLSX、Parquet）。** 表格类来源在 artifact 中是 `tables`：每个表格包含一个表头（第一个有值的行，XLSX 中可以是两行，见下文；Parquet 文件则是其 schema）、由其包含的每个值决定类型的列（`string`、`number`、`bool`、`date`、`datetime`、`time`、`duration` 或 `mixed`；空单元格和错误不计入；日期和日期时间混合的列是 `datetime`），以及其行的值。相同的行也是块，每块二十行，且最多 1,000 个字符（更长的行单独成块，仍在分块默认的 1,500 个字符之内，因此一个分块引用其包含的行），每行是一行 `column: value` 键值对，通过工作表和行号引用，因此词法检索和向量检索像检索任何段落一样检索它们；其下没有文本行的表头（没有行，或 Parquet 文件的每个值都被排除）在它给出了列名时自成一块，块从有文本的行开始，也在有文本的行结束。列名最多取其表头单元格的 500 个字符（被截得更短的是失败单元，`<table> header`）。浮点数的行文本是工作表所显示的内容，保留 15 位有效数字（`0.1+0.2` 读作 `0.3`），表格保留其精确值。在 CSV 和 XLSX 中，不是 JSON 数字的数值（超出有符号 64 位的整数、无穷大、NaN）按浮点数或文本读取，其他规则都不适用的值（5,000 位数字的样式索引、四舍五入后超过 9999 年的日期）按数字或文本读取，绝不会使文件失败；Parquet 按各列的类型读取每个值（见下文）。

**CSV。** 名为 `.tsv` 的文件，分隔符是制表符，不使用引号。否则分隔符是逗号、分号、制表符或竖线（未以此类文件名发送的制表符分隔文件会被探测，因此引号按 CSV 的方式读取），根据文件前 4 KiB 中完整行里带引号的字段来猜测，或根据文件前 64 KiB 中完整行里分隔符的计数来猜测（仅当第一行超出样本时，样本才会在行中间被截断）；字段用 `"` 引起，其中的引号加倍，无论探测器如何猜测，值都是文本，除非它写成普通数字、ISO 日期或 ISO 日期时间（保留其时区）。一行只保留其非空字段。超过一兆字节的字段、超过 8 MiB 的记录，或读取器无法闭合的引号，会使从该处起的各行失败。

**XLSX。** 工作簿、其样式、其共享字符串和其工作表在解压时即读取，从不作为树整体保存；工作簿的关系整体读取，来自最多 4 MiB 的部件（超出，或不是 XML，则该文件以 `corrupt` 被拒绝：没有它们就找不到任何工作表），并指明共享字符串和样式。引用了工作簿中不存在的共享字符串的单元格读作空，artifact 会丢失 `shared_strings`。工作表名称最多 500 个字符（被截得更短的是失败单元，`sheet names`）。工作表按工作簿的顺序读取（图表工作表或对话框工作表不含单元格；宏工作表或任何其他类型的工作表不读取，单独失败），每个工作表是一个表格；Strict Open XML 工作簿会以 `unsupported_format` 被拒绝；关系没有指向任何部件的工作表单独失败。单元格按工作簿保存的内容读取：共享字符串或内联字符串（不含其拼音注音；只有空白的字符串为空，与 CSV 字段相同）、数字、布尔值、错误（`{"error": "#DIV/0!"}`），或在其数字格式为日期格式时读作日期（内置格式 14-17 和 22、东亚版 Excel 的 27-31、36 和 50-58，或最多 255 个字符、即 Excel 自身上限的、含日期字母的自定义代码），采用 1900 系统（Excel 的 1900-02-29 读作文本）或 1904 系统，精确到最接近的秒。一天中时间的格式读作 `time`，已用时间格式（如 `[h]:mm`）读作 `duration`。公式读作其缓存的值；没有缓存值的读作空，artifact 会丢失 `formula_values`。超过一兆字节的值（无论内联还是共享）以及超过第 16,384 列的值会被排除并计数，同一位置写了两次的单元格也是如此（其较早的值丢失）。合并区域的第一个值填充其每个单元格，因此跨列合并的表头会为每列命名；跨两行的表头，即第一行中跨列合并的区域，把第二行的文本单元格归在其下（`2025` 在 `H1` 和 `H2` 之上），会由两者共同为每列命名（`2025 / H1`；其上没有内容的列取第二行的名称），且 `header_rows` 为 2；第二个表头行计入表格所含的行数。第二行中其他任何不是从第一行向下合并而来的单元格，无论是否为文本，都会使它成为数据。单元格预算未展开的区域不做分组；区域之下的数字或日期（写成数字的 `2024 | 2025`）同样读作数据。合并在整个第一行之上的标题同样适用此规则，并位于每个名称之前（`Sales 2025 / Region`）。第一行数据全是文本、且位于覆盖其所填每一列的合并区域之下的情形也是如此（`Name` 在 `Alice | Smith` 之上）：没有任何依据能把它与分组之下的名称区分开，因此它被读作第二个表头行，列保留这些名称，直到工作表被修改。合并区域不会填充超过所保存最后一行的行，会使行数超出表格所含行数的合并会在该处停止，并成为失败单元。没有指定位置的行或单元格取其前一个之后的位置。隐藏的工作表会被读取并标记为 `attrs.hidden`，损坏的工作表或根不是工作表（另一个命名空间）的工作表单独失败；无法读取到末尾的共享字符串或样式保留已读取的部分，artifact 会丢失 `shared_strings` 或 `number_formats`。

**Parquet。** pyarrow 从内存中的字节读取文件，不使用文件系统、不使用线程，使用其系统内存池：其列取自 schema（前 16,384 列，因名称可能重复而按位置保留；其余的是失败单元，`<name> columns`），其行一次读一个行组，每批最多 1,024 行，且值的个数不超过单元格预算，按叶子列计数（结构体的每个字段各算一个）。名称不是文件的行，因此表格没有表头行（`header_rows` 为 0），其行从 1 开始计数。列的读取方式根据其类型一次性确定，因此其每个批次的读取方式相同。整数是数字，小数和超出有符号 64 位的整数（`uint64`）也是，都按其精确的数字写出，因为 JSON 数字读回时是双精度（artifact 及其段落保留每一位数字；数据集的前 24 个数字或时长列保留九位小数，因此 `decimal(38,18)` 会在此处舍入，其余的按双精度，见[数据集](#datasets)）；浮点数是数字，顶层 `float32` 或 `float16` 列的值取其自身类型下最短的十进制表示，NaN 不算值（浮点列表示缺失数字的标记），与 null 相同；布尔值、日期、时间戳（保留其时区，列没有时区则无）、一天中的时间和时长按其他读取器的写法读取，纳秒单位降为微秒（在列表、结构体或映射内部也是如此，但列表视图除外，Arrow 不能将其转换为其他元素类型）；文本是文本，UUID 取其文本，列表、结构体或映射取其 JSON（其中的字节为 base64）；其他扩展类型按其所存储的类型读取，`bool8` 读作布尔值。字节不是文本，它们、无穷大（这样浮点列仍是数字）、超过 1,048,576 个字符的值以及 Python 无法保存的值（超过 9999 年的日期）都会被排除并计数（`<name> values`，每种原因都会指明，计数涵盖已读取的行）；含有 Python 无法保存的值的批次会被反复对半拆分，直到每一部分都能转换，因此只有那一个值被排除，一列中超过 16 个这样的值（跨整个文件）后，该列其余部分不再读取而被排除，并计为此类。全是 null、NaN 或空白文本的行不是行；schema 中没有任何列的文件只有空白行，行数取自其元数据，没有行的行组被跳过；页脚声明的行数小于零时视为没有，页脚声明的各行组总行数达到 2^63 或更多的文件会以 `corrupt` 被拒绝。页面逐个解码，因此行组的大小不决定其占用的内存；超出表格预算的行不读取：即超出其用尽预算的那个批次之后的行，以及超出四百万个值，或 256 MiB 解码量，或 100,000 个行组的读取量的行，这些在批次读入 Python 之前计费（每行至少一个值，列表、结构体或映射的每个元素直至其叶子，字典条目对每个引用它的值各算一次，视图的值对每个视图各算一次（后两者针对读入 Python 的列：字节列从不复制），因此由空白行、长列表或长值构成的文件同样受限；从该处起的行是其自己的失败单元，`past what one file decodes`），按元数据计数，绝不解码；页面无法解码、或所含行数多于或少于其页脚声明的行组（行按页脚编号和计数），会使从该处起的行失败（`<name> rows N-`）。子进程的限制约束一次解码（超过时间限制的一次会使文件以 `timeout` 被拒绝，使子进程崩溃的一次则是 `resource_limit`），其环境把本地库限制为一个线程并使用系统分配器，这是地址空间限制所允许的。没有 pyarrow 的构建不声明支持 Parquet。

**边界。** 一个预算约束 artifact 的所有表格，分三部分：来源所含的内容、其表格写入的字节，以及它们索引的文本。一个来源最多含 1,000,000 个非空单元格（包括合并的单元格），其文本在 256 MiB 内按每个字符四字节计，每个表格最多 100,000 行；对剩余单元格而言过大的合并会被跳过，把单元格留给其余部分，工作簿最多读取 1,000,000 个合并区域，这是对其耗时的限制（超出时，每个区域都计为未展开、未读取）。排布各行最多花费 40 MiB，按 artifact 的 JSON 写法计算：每行的值（包括 null）、带列名的块行（包括转义）、每个块自己的字段和工作表名称，以及失败单元；表格块所含的文本最多 12 M 个字符，每个块另计 760，因为一个块至多被索引为一个分块（同一标题下的块会打包成更少的分块），而比分块更长的块每个步长一个分块，所以 artifact 的表格最多索引为 15,800 个分块，低于来源默认发布的 20,000 个；表格放不下的工作表不会留下标题。这些预算以默认值为前提：提高提取器 64 MiB 输入限制的部署（CSV 的读取耗时与其大小成正比，64 MiB 空行需 34 秒，而子进程的限制是 120 秒）可能会使大型 CSV 耗尽 CPU 时间，而把提取器的应答限制降到约 41 MiB 以下，或降低服务器的分块大小、分块步长（低于 760 个字符）或分块上限的部署，会拒绝大型表格（`resource_limit`、`too_large`）而不是截断它。超出其中任何一项的行是失败单元，被计数，其单元格只检查是否有值，从不排布；超出字节预算的表头使其表格失败，预算（其单元格、字节或文本）用尽后，其后的工作表是一个从不读取的失败单元；剩余的单元格预算仍会展开截断点所在工作表的合并，因此合并的表头会为其各列命名。工作簿的部件解压后合计最多 512 MiB，与 DOCX 相同（流式部件无论声明多大都读取至该总量并在此截断，已读取的行保留；大于 16 MiB 的标签（包括其属性）、嵌套超过 64 层、不同的元素和属性名称超过 4,096 个，或名称超过 1,024 个字符，同样只截断其所在的部件），且最多含 25 M 个元素，这限制了读取它的时间；超出此限制的工作表保留在此之前已读取的行。工作簿读取前 10,000 个工作表（其余的是一个失败单元）以及 65,536 个样式和数字格式（超出后 artifact 会丢失 `number_formats`），其共享字符串最多 256 MiB，每个字符按四字节和其占用的对象计（超出后为 `lost: shared_strings`）。一个 100,000 乘 20 个数字的工作表（解压后 62 MB，压缩后 4 MB）在子进程的限制下约 9 秒完成提取。

**契约边界。** 在应答之前，参考提取器会使每个块符合契约的边界：超过 1,024 个字符的键被排除，保留前 10,000 个，节路径保留其前 64 个条目，每个条目截断为 500 个字符。被截断的块会被标记（`attrs.keys_truncated`、`attrs.section_truncated`），artifact 的 `coverage.lost` 会指明丢失的内容（`exact_keys`、`section_path`）；块的文本和定位符仍保留其全部内容。

<a id="qualification"></a>

## 鉴定

只有当某种格式通过下列各项下限时，参考提取器才会声明支持该格式。每种格式和每个切片分别度量，因此一个良好的平均值无法掩盖某个未达标的切片。`tests/unit/test_extraction_gates.py` 读取此表，用带标注的测试样本对参考提取器打分，任何切片低于其下限即判为失败；如果参考提取器的能力声明了某种在此表中没有对应行的格式，或声称支持格式及其选项之外的任何内容，也会判为失败。PDF、DOCX 和 PPTX 在解析基准的语料上打分（`bench/docparse/corpus`、其金标准标注和 `bench/docparse/score.py`）；其他格式则使用测试中构建的带标注样本。

| 格式 | 切片 | 指标 | 下限 |
| -------- | ----------------------- | -------------- | ----- |
| pdf      | 文本层，每个切片 | 文本召回率 | 0.97  |
| pdf      | 文本层，每个切片 | 阅读顺序 | 0.95  |
| pdf      | 文本层，每个切片 | 标题 F1 | 0.95  |
| pdf      | 文本层，每个切片 | 标题层级 | 0.95  |
| pdf      | 文本层，每个切片 | 表格单元格 F1 | 0.95  |
| pdf      | 文本层，每个切片 | 定位 | 0.90  |
| pdf      | 扫描件 | 失败单元 | 1.00  |
| pdf      | 每个切片 | 已声明的损失 | 1.00  |
| docx     | 文档 | 文本召回率 | 0.98  |
| docx     | 文档 | 标题 F1 | 0.98  |
| docx     | 文档 | 标题层级 | 0.98  |
| docx     | 文档 | 表格单元格 F1 | 0.98  |
| pptx     | 幻灯片组 | 文本召回率 | 0.95  |
| pptx     | 幻灯片组 | 标题 F1 | 0.98  |
| pptx     | 幻灯片组 | 定位 | 0.90  |
| pptx     | 幻灯片组 | 备注 | 1.00  |
| pptx     | 幻灯片组 | 已声明的损失 | 1.00  |
| markdown | 样本 | 文本召回率 | 1.00  |
| markdown | 样本 | 文本精确率 | 1.00  |
| markdown | 样本 | 标题 F1 | 1.00  |
| markdown | 样本 | 标题层级 | 1.00  |
| markdown | 样本 | 定位 | 1.00  |
| html     | 样本 | 文本召回率 | 1.00  |
| html     | 样本 | 文本精确率 | 1.00  |
| html     | 样本 | 标题 F1 | 1.00  |
| html     | 样本 | 标题层级 | 1.00  |
| html     | 样本 | 表格行 | 1.00  |
| text     | 样本 | 文本召回率 | 1.00  |
| text     | 样本 | 文本精确率 | 1.00  |
| text     | 样本 | 定位 | 1.00  |
| sql      | 样本 | 语句 | 1.00  |
| sql      | 样本 | 定位 | 1.00  |
| sql      | 样本 | 名称 | 1.00  |
| toml     | 样本 | 键路径 | 1.00  |
| toml     | 样本 | 定位 | 1.00  |
| csv      | 样本 | 带类型单元格 | 1.00  |
| csv      | 样本 | 表头 | 1.00  |
| xlsx     | 样本 | 带类型单元格 | 1.00  |
| xlsx     | 样本 | 表头 | 1.00  |
| parquet  | 样本 | 带类型单元格 | 1.00  |
| parquet  | 样本 | 表头 | 1.00  |

指标说明：

- **文本召回率**、**文本精确率**、**阅读顺序**、**标题 F1**、**标题层级**、**表格单元格 F1** 和 **定位** 沿用基准评分器的定义：解析结果包含的金标准词的占比、金标准包含的解析结果词的占比、金标准中按顺序出现的块的占比、按文本匹配的标题的 F1、匹配标题中层级（按排名）一致的占比、表格单元格的 F1，以及金标准中在其所在页或幻灯片上被引用的块的占比。幻灯片不对标题层级设门槛，因为语料中每张幻灯片的标题都处于同一层级。对于 Markdown、HTML、text 和 SQL，定位是以完全一致的行范围找到的金标准块或语句的占比；对于 TOML，则是其所在块的范围包含该键所在行的键的占比。
- **失败单元**：扫描文件中，产物通过 OCR 读取（`attrs.ocr_pages`）或报告为失败、而从未当作空白读取的页面占比；OCR 关闭时，每一页都算作失败单元。
- **已声明的损失**：按基准类别统计，金标准中绘制在图像内的文本里，其所在页或幻灯片已由产物通过 OCR 读取，或在 `coverage.failed` 或 `attrs.images_unread` 中被标明为未读取的占比。
- **备注**：作为备注保存在对应幻灯片上的演讲者备注的占比。
- **表格行**：HTML 表格的行中，被保存为单独一行且单元格顺序正确的占比。
- **语句**、**名称**、**键路径**：分别为完整找到的 SQL 语句占比、在其键中找到的它们所定义或读取的对象占比，以及作为键找到的 TOML 键路径占比。
- **带类型单元格** 和 **表头**：分别为带值和类型读取的表格单元格占比，以及带名称读取的列占比，分母取金标准的数量与提取结果的数量中较大者，因此多出的行、列或表格都算作未命中。

这些检查在关闭 OCR 的条件下运行，所以无论是否安装了 OCR 引擎，读取结果都相同。

以下内容未经鉴定，因此参考提取器不声称支持：OCR 读取的文字（在提取器镜像带有该引擎时，它会读取扫描页和大图，扫描和已声明损失的检查会把它读取的页面算作已读取，但目前还没有下限来度量其文本）、较小图像、图表和示意图中的文本（会在 `attrs.images_unread` 和产物的警告中标明，但从不读取），以及作为带类型表格的 Markdown 管道表格（其行仍保持为按原样书写的一个段落）。

<a id="retrieval-floors"></a>

## 检索下限

这些下限针对的是 `knowledge.search` 在已提取文档上的检索表现，而不是参考提取器所声明的内容。`tests/integration/test_knowledge_retrieval_floors.py` 会摄取 Markdown 运行手册、SQL schema、一个 TOML 文件、CSV 表格、HTML 表格和一个 PDF，并在旁边写入文本，然后分三组提出带标注的查询；每条查询的目标都必须是第一个命中结果（**首位命中**）：

- **精确标识符**：一个错误码、一张表、一个视图、一个键路径和一个表单编号。
- **表格问题**：一张长到会被切成多块的 CSV 表格中每个块里的一行、另一张列相同的 CSV 中的一行，以及两张列相同的 HTML 表格中各取一行。
- **过滤召回**：`formats`、`block_types` 和 `tags` 过滤条件，每一种都会保留相互竞争的文档；每个命中结果都在过滤范围之内（**保持在过滤范围内**）。

当命中结果来自预期的来源，并且其片段或片段所在的标题中出现预期文本时，即计为命中（错误码通常就是所在章节的标题）。这些下限是使用集成测试所运行的 fake n-gram embedder 来测量和检查的，分块与查询使用同一个模型做嵌入，因此排名在多次运行之间不会变化；如果使用其他 embedder，该测试会跳过。像 `M-41` 这样的代码既不会命中词法路径（其各部分短于最小词项长度），也不会命中精确键路径，所以在 fake embedder 上，它是通过其章节标题上的向量路径被找到的。

| 分组     | 指标           | 下限 |
| -------- | -------------- | ---- |
| 精确标识符 | 首位命中       | 1.00 |
| 表格问题 | 首位命中       | 1.00 |
| 过滤召回 | 首位命中       | 1.00 |
| 过滤召回 | 保持在过滤范围内 | 1.00 |

<a id="structural-chunks"></a>

## 结构化分块

`chunk_artifact` 按块（block）切分，而不是对展平后的文本使用固定窗口：

- 同一父级下的连续块（某个标题的章节，或带有其键的 TOML 表）会打包成一个分块，上限为分块大小；
- 一条 SQL 语句自成一个分块，因此一次命中只引用一条语句；
- 长于分块大小的块会被切成多个窗口，每个窗口保留其所属章节；对于带有字符偏移的块，每个窗口还保留各自的行范围和字符范围（HTML 窗口，或有效 TOML 文件的窗口，引用的是其所在块的行）；
- 标题文本不会在分块文本中重复：章节路径随分块一并保存；没有文本且其下没有子章节的标题自成一个分块。

每个分块都记录切分来源块的 id、这些块的类型（类型不同时为 `mixed`）、其范围合并后的定位信息（`key_path` 等字段仅在所有块一致时才保留）以及这些块的键的并集，并记录写入时的文档修订版本和格式。

<a id="ingestion"></a>

## 摄取

`knowledge.ingest` 在 `POST /v1/knowledge.upload` 存下的原件上运行一个作业（`server/knowledge/app/ingest_run.py`，worker 为 `knowledge_ingest`）。上传时只根据文件名和媒体类型确定格式，从不读取字节内容；作业读取原件，通过上文的客户端把它发送给提取器，检查产物，把产物作为自己的原件存储（按内容寻址），切出结构化 chunk 及每个 chunk 的上下文（`chunk_context`：标题、描述和章节面包屑），对它们做嵌入（如果该命名空间已在同一模型下嵌入过某个输入，则复用其向量），然后发布该来源的下一个修订版：先确定修订版本（并检查预期的修订版本），插入作为该修订版写入的 chunk，再在来源的声明（claim）之下，若来源自确定修订版本以来已发生变化则拒绝发布，写入文档行，并撤下上一版本的 chunk。声明只覆盖这几条语句，不覆盖 chunk 的插入，因此无论来源多大，其时间限制都成立。提取器拒绝的来源会使作业以其错误码失败；没有任何已配置的提取器接受的格式会使作业以 `format_unavailable` 失败；违反约定的产物会使作业以 `invalid_artifact` 失败；提取器无法连接、超时，或返回的状态既不是结果也不是拒绝时，作业会被放回队列并带有逐渐增长的延迟（最多一小时），直到达到 `LOOM_KNOWLEDGE_INGEST_MAX_ATTEMPTS`。所有耗时步骤都运行完毕之前不会发布任何内容，因此失败或被取消的作业会让先前的修订版继续提供服务。作业行会在写入文档行之前记录一次发布所插入的 chunk 版本；当某次运行在这两步之间停止时，它的重试、失败或下一次运行会撤下这些 chunk。文档行记录写入它的作业（`ingestion_id`，元数据编辑和删除都会保留它），重跑时会在来源的所有版本行中查找记录了该作业的行，因此之后的文本写入不会将其掩盖；如果某次运行在发布中途停止（在发布阶段仍为 `processing`，并连同其 chunk 版本一起保存），而之后来源又发生了新的写入（文本写入、元数据编辑或删除），且找不到该作业的行（可能已被合并折叠掉），则以 `revision_conflict` 失败，而不是可能用较旧的文件覆盖该写入；被重试放回 pending 的作业不按此判定。文档插入若发生瞬时失败（自身超时，或被来源声明的截止时间中断），仍可能落地，因此这次运行会像崩溃一样在此停止，作业保持在发布阶段的 `processing` 状态，其 chunk 保持生效：运行会让作业的租约自行过期而不是释放它，所以在服务器时钟下租约的 TTL 用完之前没有 worker 会接手该作业，这个时间超出插入本身的界限（携带发送的启动窗口、被声明语句的服务器端限制以及提交余量），到那时插入要么已经落地，要么已被终止：下一次运行在其行已落地时将作业完成为已发布（其后写入的内容，无论是删除还是文本写入，都以后者为准），或如上所述以被超越为由使其失败，或撤下这些 chunk；已发布作业的重跑会直接结束，不会再次发布，也不会撤下它已发布的 chunk。取消是独立的一行（`loom.knowledge_ingest_cancels`），绝不是作业的一个版本，作业的版本只有持有其租约的 worker 才会写；worker 在发布之前以及接手作业时读取它，如果发现作业自己的发布已经完成，则无论之后是否有取消，作业都以已发布结束。每一轮在 `LOOM_KNOWLEDGE_INGEST_MAX_PASS_SECONDS` 限制下运行一个作业，同一来源的作业按请求顺序逐个处理（每个来源只提供最早的未完成作业，较旧的先于较新的），命名空间则轮流处理（最久未被服务的优先），在该截止时间被切断的运行或因进程停止而中断的运行都计入作业的尝试次数。

<a id="faults"></a>

## 故障

下面的每种故障都发生在已有一个版本在提供服务的来源的下一个修订版上：作业会以所示状态结束，其 `error_code` 和 `error_message` 说明原因，而继续提供服务的仍是前一个修订版的文档行和分块。临时性故障会使作业带着 `retrying` 回到 `pending`，直到用完 `LOOM_KNOWLEDGE_INGEST_MAX_ATTEMPTS`，然后以 `retries_exhausted` 失败。这些用例位于 `tests/unit/test_knowledge_ingest.py::test_a_fault_on_the_next_revision_fails_typed_and_the_earlier_one_keeps_serving`。

| 故障                                                                                            | 作业结束状态                               |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 提取器无法连接                                                                                  | 重试，然后 `failed` `retries_exhausted`    |
| 提取器响应时间超过 `LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S`                                          | 重试，然后 `failed` `retries_exhausted`    |
| 提取器返回压缩的响应（任何 `Content-Encoding`）                                                 | 重试，然后 `failed` `retries_exhausted`    |
| 提取器因超出其自身的时间限制而拒绝处理该来源                                                    | `failed` `timeout`                         |
| 未配置提取器，或该服务没有对应的解析器                                                          | `failed` `format_unavailable`              |
| 产物超过 `LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES`                                           | `failed` `resource_limit`                  |
| 产物不是 JSON、不符合约定、某个块的父块不存在、定位符超出原文件范围                             | `failed` `invalid_artifact`                |
| 对象存储在读取原文件或写入产物时失败                                                            | 重试，然后 `failed` `retries_exhausted`    |
| 嵌入器不可用或超过其期限                                                                        | 重试，然后 `failed` `retries_exhausted`    |
| 嵌入器缺陷（任何其他错误）                                                                      | `failed` `internal`                        |
| 存储在写入分块之后拒绝了文档行                                                                  | `failed` `internal`                        |

原文件已从存储中消失时，作业以 `original_gone` 失败（在同一文件中）。`tests/integration/test_knowledge_ingest_faults_live.py` 针对一个服务器及其 ClickHouse，运行以下场景：提取器宕机、某个块的父块不存在、对象存储读取失败、嵌入器宕机，以及分块写入之后文档行被拒绝，并通过 `knowledge.get` 和 `knowledge.search` 读回前一个修订版。

<a id="service-levels"></a>

## 服务级别

部署在混合负载下对 knowledge 操作的达标水平：交互式读取的 p95 和 p99，以及从 `knowledge.ingest` 到小文档的作业结束并变为 ready 所需的时间。每个操作的 p99 就是它的延迟预算（`server/settings/catalog.py` 中的 `OP_BUDGETS_P99_MS`），由一个单元测试进行检查。

| 指标                  | p95 毫秒 | p99 毫秒 |
| --------------------- | -------- | -------- |
| `knowledge.search`    | 150      | 250      |
| `knowledge.query`     | 1,000    | 1,500    |
| `knowledge.ingest`    | 40       | 60       |
| 小文档 ingest         | 20,000   | 30,000   |

`bench/knowledge_load.py` 针对服务器运行混合负载，并对照此表进行检查：同时进行小文档 ingest、一个大型 PDF 和一次 CSV 导入，并对已发布的内容执行搜索和结构化查询，同时对命名空间中未完成的作业进行采样以获得队列深度。无论之前的调用是否已返回，调用都按设定的速率到达；`--tenants` 会在多个组织中同时运行负载，因为命名空间的速率限制（`server/core/ratelimit.py`）限定了单个租户能发送的量。它会报告每个操作的 p50、p95 和 p99、错误数以及被拒绝的调用（429、503），并在任一指标超出其级别时以非零状态退出。

ingest 在整个部署范围内是有上限的：只有一个进程运行 ingest worker（在 `LOOM_BACKGROUND_WORKERS=auto` 下持有 worker 租约的 supervisor），并且它一次只运行一个作业，因此无论有多少副本提供服务，部署完成作业的速度都不会快于逐个依次运行的速度，排在大文件之后的作业必须等待该文件处理完。运行了作业的一轮之后，下一轮在 `LOOM_KNOWLEDGE_INGEST_INTERVAL_SECONDS` 之后开始（0：立即开始）；没有找到作业的一轮则等待 `LOOM_KNOWLEDGE_INGEST_IDLE_INTERVAL_SECONDS`（15 s），因此在空闲的部署上，文档最多要等待这么长时间其作业才会开始。小文档级别已将这段等待计入，并且只有在小文档到达的速度慢于 worker 完成它们的速度时才成立。

<a id="datasets"></a>

## 数据集

工件中的表（电子表格、CSV 或 Parquet 文件、PDF 中的表）还会成为带类型的数据集（`server/knowledge/app/datasets.py`），因此可以把其中的值当作值来读取，而不是当作段落。无论文件的形状如何，所有数据集都存放在两张表中，所以上传不会创建新表：

- `loom.datasets`，即目录：每个（来源、数据集、文档版本）对应一行 ReplacingMergeTree，读取时使用 `FINAL`，内容包括模式、其状态（`inferred`、`needs_clarification`、`approved`）、需要回答的问题、已存储和已拒绝的行数、提取是否保留了表中的每一个值，以及提供该数据集服务的快照。
- `loom.dataset_rows`，即行数据：列的值存放在模式为其指定的带类型槽位中，共 72 个：文本和时间放在 `s1`..`s24`（`Nullable(String)`），数字和时长（以秒计）放在 `n1`..`n24`（`Nullable(Decimal128(9))`），超出这些槽位的数字列放在 `f1`..`f8`（`Nullable(Float64)`），日期和日期时间放在 `t1`..`t8`（`Nullable(DateTime64(6, 'UTC'))`），布尔值放在 `b1`..`b8`。超出其类型槽位数量的列不会被存储，并会明确说明（`past_capacity`）。主键为 `(org, namespace, dataset_id, snapshot_id, row_id)`。

列采用提取器给出的类型；`mixed` 类型的列按文本保存。含有单元格错误的行，或含有其列类型无法容纳的值的行，会被整行拒绝并计数，前 20 行附带原因，因此数据集中的值都是有类型的：`n` 槽位中不接受 10^29 及以上的数字（四舍五入到九位小数之后），`f` 槽位中不接受 double 无法容纳的数字，也不接受 1900-2299 之外的时刻（这是 `DateTime64` 所能容纳的范围；时区会被转换为 UTC）。只有当提取保留了表中的每一个值时，数据集才是 `complete`：其行、合并单元格、值或单元格都不是失败单元，没有共享字符串丢失，且工件没有丢失值所依赖的任何能力（公式值、共享字符串、数字格式）。在以下情况下，模式会要求回答（`needs_clarification`）：存在 mixed 列、生成的名称（表头单元格为空）、重复的名称（非参考提取器可能会发送重复名称；数据集将其命名为 `<name> (2)`，参考提取器也是如此，因为列是按名称寻址的）、每个名称都读作数字或日期的表头（第一行可能是数据；对于名称并非来源中某一行的表，即 `header_rows` 为 0 的表，例如 Parquet 文件的模式，则不会提出此问题），以及没有槽位可容纳的列（每种类型给出一个回答，并指明其中的第一列）。针对单个列的回答上限为 100 个；超出之后，由列的 `inferred` 类型说明其余情况。推断在事件循环之外运行，因为一张表可能有 16,384 列之宽。数据集的 id 在其来源的每个修订版中保持不变：电子表格按其名称，CSV 或 Parquet 文件的表和 PDF 的表按其 id（PDF 的表按页面包含它们的顺序，因此在另一张表之前新增一张表，会使后一张表得到新的数据集），而被提取器拆分成多张表的电子表格则按其名称和表的 id。

摄取作业在分块之后、来源的 claim 之前写入每个数据集：先写一个空的目录行，这样中途停止的运行能找到它已写入的行；然后以每批 5,000 行的方式在新快照下写入行数据（在事件循环之外进行类型化，每批之前都会重新读取作业，因此删除了该作业的擦除操作会让其余批次停止）；最后写入其目录行，该行采用作业所用的文档版本。在该行写入之前，没有任何东西会读取它们：只要来源的现行文档行仍是发布时的版本，数据集就会被提供服务，因此文档行是分块和数据集共同的开关，对来源的文本写入或删除会使它们立即停止服务。元数据编辑（`knowledge.update_metadata`）会保留它们：在来源的 claim 之下，它在写入文档行之前，以新版本和相同的快照写入每个目录行。该行写入之后，来源早先版本的快照会被删除；在此之前停止的运行则删除自己的快照。如果来源的现行数据集已获批准，那么当其列的名称和顺序相同时，该来源的修订版会保留已批准的类型；在发布读取现行数据集之后才落地的批准（它先获取 claim）会让作业立即放回队列重新运行，且不计入尝试次数，因此该批准是被延续的，而不是被丢弃。

`knowledge.dataset_approve` 批准数据集的模式，并对其指明的列重新指定类型。重新指定类型会在新快照下，依据存储的工件重新为行指定类型，这一步在获取来源的 claim 之前完成（与摄取发布所获取的是同一个 claim）；在 claim 之下，批准会检查文档是否为其所读取的那一份、快照是否为调用方审阅过的那一份，然后写入切换到新快照的目录行（其版本在此处标记，高于它所取代的行），并删除被替换快照的行。如果批准发现另一次写入已使来源发生变动、无法获取 claim，或在其目录行发出之前失败，则不写入目录行，并删除自己的行；如果目录行的插入在发出之后失败，则保留这些行，因为该行可能已经落地。目录行是批准者的写入：其 `actor` 和 `approved_by` 指明批准者，其 `source_class` 为 `asserted`；行数据仍归上传者所有（`user_id`，以及它们自己的 `source_class`），因此用户擦除能找到它们。

快照通过轻量级 `DELETE FROM` 并设置 `lightweight_deletes_sync = 0` 来删除：一旦没有目录行提供某个快照的服务，就没有任何东西会读取它，因此没有请求需要等待它。`knowledge.delete` 会删除其所淘汰的文档版本的数据集，直至它所读取的那个版本；同时运行的摄取会写入更晚的版本，删除操作会把该版本完整地留给那次摄取（删除不获取 claim，因此可能落在摄取的各批次之间）。被延续的快照的行保留其写入时的版本，因此删除会保留任何仍由超出其界限的目录行所服务的快照的行；如果某次编辑的延续在删除读取目录之后才落地，且其版本更晚，则可能使文档在删除之后复活：其分块已被标记为删除，其数据集则在行已被删除的情况下继续提供服务，这与不带 claim 的删除和编辑竞争时的结果相同，而对来源再做一次删除即可解决二者。对已删除的来源再次删除，会再次删除其已淘汰版本中剩余的部分（例如在第一次删除运行时落地的批准所产生的快照，或 N-1 构建遗留的快照）。对已摄取来源的文本写入，会使其快照不再被提供服务，直到该来源的下一次摄取或删除。擦除会随文档一同删除该范围在两张表中的行（`documents.tombstone`）。

<a id="queries"></a>

### 查询

`knowledge.query`（`server/knowledge/app/query.py`）使用带类型的计划对数据集进行计算：最多四个属于调用方命名空间的数据集，每个都有一个别名；对其列的过滤条件，必须全部成立；将第一个之后的每个数据集与它之前的某一个做内等值连接；分组（日期或日期时间可按日、月或年分组，以 UTC 计）；以及聚合（`count`、`count_distinct`、`sum`、`avg`、`min`、`max`），或者带行 id 的行本身。计划会依据数据集的模式进行检查（`server/knowledge/domain/query.py`）：它所指明的每一列都是模式中存储的列，每个过滤值都按其列的类型来读取（与行的值相同，但超过九位小数的小数会被拒绝而不是四舍五入；以 double 保存的数字列按 double 比较），每个比较、连接、分组和聚合都是其列的类型所允许的；连接键必须位于同一种槽位中，因为 decimal 和 double 没有共同类型。它会编译为一条针对 `loom.dataset_rows` 的只读语句（`server/knowledge/store/dataset_query.py`），仅由槽位名、结果名 `c0`、`c1` 等以及带类型的参数构建，因此调用方写入的任何内容都不是 SQL。每个数据集都是一个子查询，限定在其快照以及调用方的 org 和命名空间内，并在任何连接之前应用它自己的过滤条件，因此其他租户或快照的行永远不会进入计数。decimal 列的求和在 `Decimal256` 中进行，任何数据集的行都不会使其溢出；平均值是该和除以计数，按 18 位小数相除并四舍五入到九位（ClickHouse 对 decimal 的 `avg` 是 double，而 decimal 除法会截断）；数据集中超出前 24 个数字或时长列的数字列以 double 保存，因此也以 double 求和和求平均。

每个数据集都在其来源的现行文档所提供的快照上读取；模式需要回答（`needs_clarification`）的数据集会被拒绝，直到它获得批准。如果设置了 `LOOM_CH_READER_USER`，语句会在调用方限定的上限之下，以只读的 reader 用户运行（`ch.caller_shaped`），因此超出部署对单个请求所允许的行数、时间或内存的计划会失败（`422`），而不是返回聚合的一部分。在行被释放之前，每个数据集必须仍由所读取的快照提供服务（发布或重新指定类型的批准会提供另一个快照，并立即删除已读取的行而不等待；擦除则使其不再提供任何快照；元数据编辑会保留它）：如果在语句运行期间快照被替换或擦除，则返回 `409 PRECONDITION_FAILED`，需要重新运行，在查询查找数据集期间落地的发布也是如此。结果在其回执中列出所读取的每个快照，附带经过验证的计划、语句及其参数；当数据集的提取遗漏了表的一部分或拒绝了某些行时，结果为 `complete: false`，并说明原因。不会存储任何内容：回执就是响应。

带 `datasets` 的 `knowledge.synthesize`（`server/knowledge/app/synthesize.py`，提示词和对回复的解析位于 `server/knowledge/domain/answer_plan.py`）会向模型发出一次请求，依据任务以及每个数据集的别名、名称、行数和存储的列，请其给出一个 `knowledge.query` 计划，或者给出它需要提出的问题（`ambiguous`）。这些数据集属于调用方：计划自带的 `datasets`、`org` 和 `namespace` 会被丢弃。计划会作为 `knowledge.query` 的输入进行验证，并由其处理程序运行，因此与任何查询一样，会依据模式检查、固定快照、设定界限并重新验证；被其中任一环节拒绝的计划，会连同原因再提议一次，之后回答将放弃（`invalid_plan`）。结果的列和前 50 行，连同其可能未涵盖的内容，构成给 reduce 的又一条笔记，以 `[knowledge.query#1]` 的形式引用，并像分块引用一样进行落地校验（`ground_citations`），因此对未运行的计算的引用会被移除。列名、数据集名称和任务对计划而言都是不受信任的输入，而计划本身不授予任何权限：查询在调用方的范围内运行，若设置了 reader 用户，则以该用户运行。

<a id="dependencies"></a>

## 依赖

参考提取器的解析器需要：SQL 使用 `sqlglot`，PDF 使用 `pypdf`（PDF 若以 AES 加密，还需要 `cryptography`），Parquet 使用 `pyarrow`，其余格式只用标准库。它们随服务一同安装（`extractor/pyproject.toml`），在开发环境中则通过 `extractor` extra 安装；服务器的镜像不包含其中任何一个。提取器的镜像（`extractor/Dockerfile`，`ghcr.io/clickhouse/loom-extractor`）把该软件包及其锁定的依赖（`extractor/uv.lock`）安装到由 root 所有的 venv 中，并以一个不拥有其中任何内容的用户运行服务，因此子进程的 `sys.path` 上没有任何文件是子进程可写的。compose 栈和 Helm chart 都让它与服务器分开运行：Compose 把它放在仅与服务器共享的内部网络上，chart 则把它置于只允许 Loom 的 pod 访问、且不允许任何出站流量的 NetworkPolicy 之后，除自己的令牌外不持有任何凭据；无论哪种方式，当提取单独运行时（`LOOM_EXTRACTOR_CONCURRENCY` 为 1，即默认值），提取过程都不会创建任何 socket（[部署](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#container-images)，[Kubernetes](https://github.com/ClickHouse/loom/blob/main/docs/operations/kubernetes.md#document-extractor)）。

<a id="invariants"></a>

## 不变量

- 文本格式的内容会写入 blocks；解析器无法结构化的部分会记录在 `coverage` 中（失败的单元、丢失的能力），绝不会被静默丢弃。只有上文列出的 HTML 元素是有意省略的。
- block 的 locator 指向它所来源的源文本。
- artifact 以其字节的 SHA-256 作为地址，且永不修改；解析器变更会提升该解析器的 `PARSER_VERSION`，因此其输出是一个新的 artifact。
- 提取过程从不执行被解析的内容。
- 服务器不解析任何原始文件：每种格式都交给 extractor 服务处理，其返回的任何内容在 `parse_artifact` 接受之前都不会被使用。

<a id="source-entry-points"></a>

## 源码入口

| 内容                       | 位置                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| 产物                       | `server/knowledge/domain/extract/artifact.py` (`Artifact`, `Block`, `Locator`, `Coverage`)      |
| 响应检查                   | `server/knowledge/domain/extract/validate.py` (`parse_artifact`)                                |
| 格式路由                   | `server/core/document_formats.py` (`format_of`)                                                 |
| 调用提取器                 | `server/knowledge/app/extractors.py` (`extract`, `available_formats`)                           |
| 结构化分块                 | `server/knowledge/domain/extract/structural.py` (`chunk_artifact`)                              |
| 数据集模式与类型           | `server/knowledge/domain/datasets.py` (`infer`, `typed_rows`)                                   |
| 数据集发布与审批           | `server/knowledge/app/datasets.py`，行数据位于 `server/knowledge/store/datasets.py`             |
| 数据集查询                 | `server/knowledge/app/query.py`，查询计划位于 `domain/query.py`，SQL 位于 `store/dataset_query.py` |
| 参考服务                   | `extractor/loom_extractor/service.py`，每次提取对应一个 `child.py` 进程                         |
| 格式检测与解码             | `extractor/loom_extractor/source.py` (`detect_format`, `decode`, `extract`)                     |
| SQL                        | `extractor/loom_extractor/sql.py` (`extract_sql`, `detect_dialect`)                             |
| TOML                       | `extractor/loom_extractor/tomlfile.py`                                                          |
| Markdown、纯文本、HTML     | `extractor/loom_extractor/text.py`，标题规则位于 `markdown.py`                                  |
