trustgraph/docs/tech-specs/zh-cn/large-document-loading.zh-cn.md

---
layout: default
title: "大型文档加载技术规范"
parent: "Chinese (Beta)"
---

# 大型文档加载技术规范

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## 概述

本规范解决了在将大型文档加载到 TrustGraph 时出现的可扩展性和用户体验问题。 当前架构将文档上传视为单个原子操作，这会在管道的多个阶段导致内存压力，并且不为用户提供任何反馈或恢复选项。

本次实施的目标是以下用例：


1. **大型 PDF 处理**: 在不耗尽内存的情况下，上传和处理数百兆字节的 PDF 文件。

2. **可恢复的上传**: 允许中断的上传从中断的地方继续，而不是重新开始。
   
3. **进度反馈**: 向用户提供有关上传和处理进度的实时可见性。
   
4. **内存高效处理**: 以流式方式处理文档，而无需将整个文件保存在内存中。
   

   ## 目标


**增量上传**: 支持通过 REST 和 WebSocket 进行分块文档上传。
**可恢复传输**: 启用从中断的上传中恢复。
**进度可见性**: 向客户端提供上传/处理进度反馈。
**内存效率**: 消除整个管道中的完整文档缓冲。
**向后兼容性**: 现有的小型文档工作流程保持不变。
**流式处理**: PDF 解码和文本分块操作在流上进行。

## 背景


### 当前架构

文档提交流程如下：

1. **客户端** 通过 REST (`POST /api/v1/librarian`) 或 WebSocket 提交文档。
2. **API 网关** 接收包含 base64 编码的文档内容的完整请求。
3. **LibrarianRequestor** 将请求转换为 Pulsar 消息。
4. **Librarian 服务** 接收消息，将文档解码到内存中。
5. **BlobStore** 将文档上传到 Garage/S3。
6. **Cassandra** 存储包含对象引用的元数据。
7. 为了处理：从 S3 中检索文档，解码，分块——所有都在内存中。

关键文件：
REST/WebSocket 入口：`trustgraph-flow/trustgraph/gateway/service.py`
Librarian 核心：`trustgraph-flow/trustgraph/librarian/librarian.py`
Blob 存储：`trustgraph-flow/trustgraph/librarian/blob_store.py`
Cassandra 表：`trustgraph-flow/trustgraph/tables/library.py`
API 模式：`trustgraph-base/trustgraph/schema/services/library.py`

### 当前限制

当前设计存在几个相互影响的内存和用户体验问题：

1. **原子上传操作**: 整个文档必须在一个请求中传输。
   大型文档需要长时间运行的请求，并且在连接失败时没有进度指示和重试机制。
   

2. **API 设计**: 无论是 REST 还是 WebSocket API，都期望在单个消息中接收完整的文档。
   模式 (`LibrarianRequest`) 包含一个 `content` 字段，其中包含整个 base64 编码的文档。
   

3. **Librarian 内存**: librarian 服务在将文档上传到 S3 之前，将其完全解码到内存中。
   对于一个 500MB 的 PDF 文件，这意味着需要在进程内存中保留 500MB+。
   

4. **PDF 解码器内存**: 当处理开始时，PDF 解码器将整个 PDF 文件加载到内存中以提取文本。
   PyPDF 和类似的库通常需要访问整个文档。
   

5. **分块器内存**: 文本分块器接收完整的提取文本，并在生成块时将其保存在内存中。
   

**内存影响示例** (500MB PDF)：
网关：~700MB (base64 编码开销)
Librarian：~500MB (解码后的字节)
PDF 解码器：~500MB + 提取缓冲区
分块器：提取的文本 (可变，可能高达 100MB+)

对于单个大型文档，峰值内存总和可能超过 2GB。

## 技术设计

### 设计原则

1. **API 接口**: 所有客户端交互都通过 librarian API 进行。客户端
   没有直接访问或了解底层 S3/Garage 存储的权限。

2. **S3 多部分上传**: 使用标准的 S3 多部分上传。
   这在所有兼容 S3 的系统中都得到广泛支持 (AWS S3, MinIO, Garage,
   Ceph, DigitalOcean Spaces, Backblaze B2 等)，确保可移植性。

3. **原子完成**: S3 多部分上传本质上是原子的 - 上传的
   部分在调用 `CompleteMultipartUpload` 之前是不可见的。不需要临时
   文件或重命名操作。

4. **可跟踪的状态**: 上传会话在 Cassandra 中跟踪，从而
   提供对未完成上传的可见性，并启用恢复功能。

### 分块上传流程

```
Client                    Librarian API                   S3/Garage
  │                            │                              │
  │── begin-upload ───────────►│                              │
  │   (metadata, size)         │── CreateMultipartUpload ────►│
  │                            │◄── s3_upload_id ─────────────│
  │◄── upload_id ──────────────│   (store session in          │
  │                            │    Cassandra)                │
  │                            │                              │
  │── upload-chunk ───────────►│                              │
  │   (upload_id, index, data) │── UploadPart ───────────────►│
  │                            │◄── etag ─────────────────────│
  │◄── ack + progress ─────────│   (store etag in session)    │
  │         ⋮                  │         ⋮                    │
  │   (repeat for all chunks)  │                              │
  │                            │                              │
  │── complete-upload ────────►│                              │
  │   (upload_id)              │── CompleteMultipartUpload ──►│
  │                            │   (parts coalesced by S3)    │
  │                            │── store doc metadata ───────►│ Cassandra
  │◄── document_id ────────────│   (delete session)           │
```

客户端从不直接与 S3 交互。 库（librarian）在内部将我们的分块上传 API 转换为 S3 的多部分操作。

### Librarian API 操作
### 图书管理员API操作

#### `begin-upload`

初始化一个分块上传会话。

请求：
```json
{
  "operation": "begin-upload",
  "document-metadata": {
    "id": "doc-123",
    "kind": "application/pdf",
    "title": "Large Document",
    "user": "user-id",
    "tags": ["tag1", "tag2"]
  },
  "total-size": 524288000,
  "chunk-size": 5242880
}
```

响应：
```json
{
  "upload-id": "upload-abc-123",
  "chunk-size": 5242880,
  "total-chunks": 100
}
```

馆员：
1. 生成一个唯一的 `upload_id` 和 `object_id` (用于对象存储的 UUID)
2. 调用 S3 `CreateMultipartUpload`，接收 `s3_upload_id`
3. 在 Cassandra 中创建会话记录
4. 将 `upload_id` 返回给客户端

#### `upload-chunk`

上传单个分块。

请求：
```json
{
  "operation": "upload-chunk",
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "content": "<base64-encoded-chunk>"
}
```

响应：
```json
{
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "chunks-received": 1,
  "total-chunks": 100,
  "bytes-received": 5242880,
  "total-bytes": 524288000
}
```

馆员：
1. 通过 `upload_id` 查找会话。
2. 验证所有权（用户必须与会话创建者匹配）。
3. 使用块数据调用 S3 `UploadPart`，接收 `etag`。
4. 使用块索引和 etag 更新会话记录。
5. 将进度返回给客户端。

失败的块可以重试 - 只需要再次发送相同的 `chunk-index`。

#### `complete-upload`

完成上传并创建文档。

请求：
```json
{
  "operation": "complete-upload",
  "upload-id": "upload-abc-123"
}
```

响应：
```json
{
  "document-id": "doc-123",
  "object-id": "550e8400-e29b-41d4-a716-446655440000"
}
```

馆员：
1. 查找会话，验证是否接收到所有分块。
2. 使用 part etags 调用 S3 `CompleteMultipartUpload` (S3 内部合并分块，馆员无需消耗内存)。
   3. 在 Cassandra 中创建文档记录，包含元数据和对象引用。
4. 删除上传会话记录。
5. 将文档 ID 返回给客户端。


#### `abort-upload`

取消正在进行的上传。

请求：
```json
{
  "operation": "abort-upload",
  "upload-id": "upload-abc-123"
}
```

馆员：
1. 调用 S3 `AbortMultipartUpload` 清理部分数据。
2. 从 Cassandra 中删除会话记录。

#### `get-upload-status`

查询上传状态（用于断点续传功能）。

请求：
```json
{
  "operation": "get-upload-status",
  "upload-id": "upload-abc-123"
}
```

响应：
```json
{
  "upload-id": "upload-abc-123",
  "state": "in-progress",
  "chunks-received": [0, 1, 2, 5, 6],
  "missing-chunks": [3, 4, 7, 8],
  "total-chunks": 100,
  "bytes-received": 36700160,
  "total-bytes": 524288000
}
```

#### `list-uploads`

获取用户未完成上传的列表。

请求：
```json
{
  "operation": "list-uploads"
}
```

响应：
```json
{
  "uploads": [
    {
      "upload-id": "upload-abc-123",
      "document-metadata": { "title": "Large Document", ... },
      "progress": { "chunks-received": 43, "total-chunks": 100 },
      "created-at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### 上传会话存储

在 Cassandra 中跟踪正在进行的上传：

```sql
CREATE TABLE upload_session (
    upload_id text PRIMARY KEY,
    user text,
    document_id text,
    document_metadata text,      -- JSON: title, kind, tags, comments, etc.
    s3_upload_id text,           -- internal, for S3 operations
    object_id uuid,              -- target blob ID
    total_size bigint,
    chunk_size int,
    total_chunks int,
    chunks_received map<int, text>,  -- chunk_index → etag
    created_at timestamp,
    updated_at timestamp
) WITH default_time_to_live = 86400;  -- 24 hour TTL

CREATE INDEX upload_session_user ON upload_session (user);
```

**TTL 行为：**
如果未完成，会话将在 24 小时后过期。
当 Cassandra TTL 过期时，会话记录将被删除。
孤立的 S3 分片由 S3 生命周期策略清理（在桶上配置）。

### 故障处理和原子性

**分块上传失败：**
客户端重试失败的分块（使用相同的 `upload_id` 和 `chunk-index`）。
S3 `UploadPart` 对于相同的分片编号是幂等的。
会话跟踪哪些分块已成功。

**客户端在上传过程中断连接：**
会话仍然存在于 Cassandra 中，记录了已接收的分块。
客户端可以调用 `get-upload-status` 以查看缺少的内容。
通过仅上传缺失的分块来恢复，然后调用 `complete-upload`。

**完整上传失败：**
S3 `CompleteMultipartUpload` 是原子性的 - 要么完全成功，要么完全失败。
如果失败，分片仍然存在，客户端可以重试 `complete-upload`。
永远不会出现部分文档。

**会话过期：**
Cassandra TTL 在 24 小时后删除会话记录。
S3 桶生命周期策略清理不完整的多部分上传。
不需要手动清理。

### S3 多部分原子性

S3 多部分上传提供了内置的原子性：

1. **分片不可见：** 上传的分片不能作为对象访问。
   它们仅作为不完整的多部分上传的分片存在。

2. **原子完成：** `CompleteMultipartUpload` 要么成功（对象
   以原子方式出现），要么失败（未创建对象）。 没有部分状态。

3. **无需重命名：** 最终对象键在
   `CreateMultipartUpload` 时指定。 分片直接合并到该键。

4. **服务器端合并：** S3 内部合并分片。 库管理员
   永远不会读取分片 - 无论文档大小如何，都没有内存开销。

### BlobStore 扩展

**文件：** `trustgraph-flow/trustgraph/librarian/blob_store.py`

添加多部分上传方法：

```python
class BlobStore:
    # Existing methods...

    def create_multipart_upload(self, object_id: UUID, kind: str) -> str:
        """Initialize multipart upload, return s3_upload_id."""
        # minio client: create_multipart_upload()

    def upload_part(
        self, object_id: UUID, s3_upload_id: str,
        part_number: int, data: bytes
    ) -> str:
        """Upload a single part, return etag."""
        # minio client: upload_part()
        # Note: S3 part numbers are 1-indexed

    def complete_multipart_upload(
        self, object_id: UUID, s3_upload_id: str,
        parts: List[Tuple[int, str]]  # [(part_number, etag), ...]
    ) -> None:
        """Finalize multipart upload."""
        # minio client: complete_multipart_upload()

    def abort_multipart_upload(
        self, object_id: UUID, s3_upload_id: str
    ) -> None:
        """Cancel multipart upload, clean up parts."""
        # minio client: abort_multipart_upload()
```

### 分块大小的考量

**S3 最小值**: 每个分块 5MB (除了最后一个分块)
**S3 最大值**: 每个上传 10,000 个分块
**实际默认值**: 5MB 分块
  500MB 文档 = 100 个分块
  5GB 文档 = 1,000 个分块
**进度粒度**: 较小的分块 = 更精细的进度更新
**网络效率**: 较大的分块 = 更少的网络请求

分块大小可以在一定范围内由客户端配置 (5MB - 100MB)。

### 文档处理：流式检索

上传流程旨在高效地将文档存储到存储系统中。处理流程旨在提取和分块文档，而无需将整个文档加载到内存中。



#### 设计原则：标识符，而非内容

目前，当触发处理时，文档内容通过 Pulsar 消息传递。这会将整个文档加载到内存中。 应该这样做：


Pulsar 消息仅携带 **文档标识符**
处理程序直接从 librarian 获取文档内容
获取过程是 **流式传输到临时文件**
文档特定的解析 (PDF、文本等) 使用文件，而不是内存缓冲区

这使得 librarian 不依赖于文档结构。 PDF 解析、文本
提取和其他特定于格式的逻辑保留在各自的解码器中。

#### 处理流程

```
Pulsar              PDF Decoder                Librarian              S3
  │                      │                          │                  │
  │── doc-id ───────────►│                          │                  │
  │  (processing msg)    │                          │                  │
  │                      │                          │                  │
  │                      │── stream-document ──────►│                  │
  │                      │   (doc-id)               │── GetObject ────►│
  │                      │                          │                  │
  │                      │◄── chunk ────────────────│◄── stream ───────│
  │                      │   (write to temp file)   │                  │
  │                      │◄── chunk ────────────────│◄── stream ───────│
  │                      │   (append to temp file)  │                  │
  │                      │         ⋮                │         ⋮        │
  │                      │◄── EOF ──────────────────│                  │
  │                      │                          │                  │
  │                      │   ┌──────────────────────────┐              │
  │                      │   │ temp file on disk        │              │
  │                      │   │ (memory stays bounded)   │              │
  │                      │   └────────────┬─────────────┘              │
  │                      │                │                            │
  │                      │   PDF library opens file                    │
  │                      │   extract page 1 text ──►  chunker          │
  │                      │   extract page 2 text ──►  chunker          │
  │                      │         ⋮                                   │
  │                      │   close file                                │
  │                      │   delete temp file                          │
```

#### 图书管理员流式 API

添加一个流式文档检索操作：

**`stream-document`**

请求：
```json
{
  "operation": "stream-document",
  "document-id": "doc-123"
}
```

响应：流式传输的二进制数据块（不是单个响应）。

对于 REST API，这会返回一个带有 `Transfer-Encoding: chunked` 的流式响应。

对于内部服务之间的调用（处理器到图书管理员），可能如下：
通过预签名 URL 进行直接 S3 流式传输（如果内部网络允许）。
通过服务协议进行分块响应。
一个专用的流式传输端点。

关键要求：数据以块的形式流动，永远不会完全缓存在图书管理员中。

#### PDF 解码器更改

**当前实现**（占用大量内存）：

```python
def decode_pdf(document_content: bytes) -> str:
    reader = PdfReader(BytesIO(document_content))  # full doc in memory
    text = ""
    for page in reader.pages:
        text += page.extract_text()  # accumulating
    return text  # full text in memory
```

**新实现** (临时文件，增量式)：

```python
def decode_pdf_streaming(doc_id: str, librarian_client) -> Iterator[str]:
    """Yield extracted text page by page."""

    with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
        # Stream document to temp file
        for chunk in librarian_client.stream_document(doc_id):
            tmp.write(chunk)
        tmp.flush()

        # Open PDF from file (not memory)
        reader = PdfReader(tmp.name)

        # Yield pages incrementally
        for page in reader.pages:
            yield page.extract_text()

        # tmp file auto-deleted on context exit
```

内存配置：
临时文件在磁盘上：大小为 PDF 文件的大小（磁盘很便宜）
内存中：一次加载一页的文本
峰值内存：受限，与文档大小无关

#### 文本文档解码器更改

对于纯文本文档，更加简单 - 不需要临时文件：

```python
def decode_text_streaming(doc_id: str, librarian_client) -> Iterator[str]:
    """Yield text in chunks as it streams from storage."""

    buffer = ""
    for chunk in librarian_client.stream_document(doc_id):
        buffer += chunk.decode('utf-8')

        # Yield complete lines/paragraphs as they arrive
        while '\n\n' in buffer:
            paragraph, buffer = buffer.split('\n\n', 1)
            yield paragraph + '\n\n'

    # Yield remaining buffer
    if buffer:
        yield buffer
```

文本文件可以直接流式传输，无需临时文件，因为它们的结构是线性的。


#### 流式分块集成

分块器接收文本的迭代器（页面或段落），并逐步生成块：


```python
class StreamingChunker:
    def __init__(self, chunk_size: int, overlap: int):
        self.chunk_size = chunk_size
        self.overlap = overlap

    def process(self, text_stream: Iterator[str]) -> Iterator[str]:
        """Yield chunks as text arrives."""
        buffer = ""

        for text_segment in text_stream:
            buffer += text_segment

            while len(buffer) >= self.chunk_size:
                chunk = buffer[:self.chunk_size]
                yield chunk
                # Keep overlap for context continuity
                buffer = buffer[self.chunk_size - self.overlap:]

        # Yield remaining buffer as final chunk
        if buffer.strip():
            yield buffer
```

#### 端到端处理流程

```python
async def process_document(doc_id: str, librarian_client, embedder):
    """Process document with bounded memory."""

    # Get document metadata to determine type
    metadata = await librarian_client.get_document_metadata(doc_id)

    # Select decoder based on document type
    if metadata.kind == 'application/pdf':
        text_stream = decode_pdf_streaming(doc_id, librarian_client)
    elif metadata.kind == 'text/plain':
        text_stream = decode_text_streaming(doc_id, librarian_client)
    else:
        raise UnsupportedDocumentType(metadata.kind)

    # Chunk incrementally
    chunker = StreamingChunker(chunk_size=1000, overlap=100)

    # Process each chunk as it's produced
    for chunk in chunker.process(text_stream):
        # Generate embeddings, store in vector DB, etc.
        embedding = await embedder.embed(chunk)
        await store_chunk(doc_id, chunk, embedding)
```

在任何时候，完整的文档或完整的提取文本都不会保存在内存中。

#### 临时文件注意事项

**位置：** 使用系统临时目录（`/tmp` 或等效目录）。对于
容器化部署，请确保临时目录有足够的空间，并且位于快速存储上（如果可能，不要使用网络挂载）。


**清理：** 使用上下文管理器（`with tempfile...`）以确保即使在出现异常时也能进行清理。


**并发处理：** 每个处理任务都有自己的临时文件。
并行文档处理之间不会发生冲突。

**磁盘空间：** 临时文件是短暂存在的（处理过程中的持续时间）。
对于一个 500MB 的 PDF 文件，在处理过程中需要 500MB 的临时空间。如果磁盘空间受限，可以在上传时强制执行大小限制。


### 统一处理接口：子文档

PDF 提取和文本文档处理需要输入到相同的下游流程（分块 → 嵌入 → 存储）。为了实现这一点，并使用一致的“按 ID 检索”接口，提取的文本块被存储回 librarian，作为子文档。




#### 使用子文档的处理流程

```
PDF Document                                         Text Document
     │                                                     │
     ▼                                                     │
pdf-extractor                                              │
     │                                                     │
     │ (stream PDF from librarian)                         │
     │ (extract page 1 text)                               │
     │ (store as child doc → librarian)                    │
     │ (extract page 2 text)                               │
     │ (store as child doc → librarian)                    │
     │         ⋮                                           │
     ▼                                                     ▼
[child-doc-id, child-doc-id, ...]                    [doc-id]
     │                                                     │
     └─────────────────────┬───────────────────────────────┘
                           ▼
                       chunker
                           │
                           │ (receives document ID)
                           │ (streams content from librarian)
                           │ (chunks incrementally)
                           ▼
                    [chunks → embedding → storage]
```

分块器具有一个统一的接口：
接收文档 ID（通过 Pulsar）
从 Librarian 流式传输内容
将其分块

它不知道也不关心该 ID 指的是：
用户上传的文本文档
从 PDF 页面提取的文本块
任何未来的文档类型

#### 子文档元数据

扩展文档模式以跟踪父/子关系：

```sql
-- Add columns to document table
ALTER TABLE document ADD parent_id text;
ALTER TABLE document ADD document_type text;

-- Index for finding children of a parent
CREATE INDEX document_parent ON document (parent_id);
```

**文档类型：**

| `document_type` | 描述 |
|-----------------|-------------|
| `source` | 用户上传的文档（PDF、文本等） |
| `extracted` | 源自源文档（例如，PDF 页面文本） |

**元数据字段：**

| 字段 | 源文档 | 提取的子文档 |
|-------|-----------------|-----------------|
| `id` | 用户提供或生成 | 生成（例如，`{parent-id}-page-{n}`） |
| `parent_id` | `NULL` | 父文档 ID |
| `document_type` | `source` | `extracted` |
| `kind` | `application/pdf`，等等 | `text/plain` |
| `title` | 用户提供 | 生成（例如，“Report.pdf 的第 3 页”） |
| `user` | 经过身份验证的用户 | 与父文档相同 |

#### 子文档的 Librarian API

**创建子文档**（内部，由 pdf-extractor 使用）：

```json
{
  "operation": "add-child-document",
  "parent-id": "doc-123",
  "document-metadata": {
    "id": "doc-123-page-1",
    "kind": "text/plain",
    "title": "Page 1"
  },
  "content": "<base64-encoded-text>"
}
```

对于较小的提取文本（典型页面文本通常小于 100KB），单次上传是可以接受的。对于非常大的文本提取，可以使用分块上传。



**列出子文档（用于调试/管理）：**

```json
{
  "operation": "list-children",
  "parent-id": "doc-123"
}
```

响应：
```json
{
  "children": [
    { "id": "doc-123-page-1", "title": "Page 1", "kind": "text/plain" },
    { "id": "doc-123-page-2", "title": "Page 2", "kind": "text/plain" },
    ...
  ]
}
```

#### 用户可见的行为

**`list-documents` 默认行为：**

```sql
SELECT * FROM document WHERE user = ? AND parent_id IS NULL;
```

只有顶层（源）文档才会出现在用户的文档列表中。
子文档默认会被过滤掉。

**可选的包含子文档标志**（用于管理员/调试）：

```json
{
  "operation": "list-documents",
  "include-children": true
}
```

#### 级联删除

当父级文档被删除时，所有子级必须被删除：

```python
def delete_document(doc_id: str):
    # Find all children
    children = query("SELECT id, object_id FROM document WHERE parent_id = ?", doc_id)

    # Delete child blobs from S3
    for child in children:
        blob_store.delete(child.object_id)

    # Delete child metadata from Cassandra
    execute("DELETE FROM document WHERE parent_id = ?", doc_id)

    # Delete parent blob and metadata
    parent = get_document(doc_id)
    blob_store.delete(parent.object_id)
    execute("DELETE FROM document WHERE id = ? AND user = ?", doc_id, user)
```

#### 存储注意事项

提取的文本块会重复内容：
原始 PDF 文件存储在 Garage 中
每个页面的提取文本也存储在 Garage 中

这种权衡方案可以实现：
**统一的分块接口**: 分块器始终通过 ID 获取数据
**恢复/重试**: 可以在分块阶段重新启动，而无需重新提取 PDF
**调试**: 可以检查提取的文本
**职责分离**: PDF 提取器和分块器是独立的服务

对于一个 500MB 的 PDF 文件，其中包含 200 页，平均每页 5KB 的文本：
PDF 存储：500MB
提取的文本存储：约 1MB
额外开销：可以忽略不计

#### PDF 提取器输出

PDF 提取器在处理文档后：

1. 从 librarian 流式传输 PDF 到临时文件
2. 逐页提取文本
3. 对于每一页，将提取的文本作为子文档通过 librarian 存储
4. 将子文档 ID 发送到分块器队列

```python
async def extract_pdf(doc_id: str, librarian_client, output_queue):
    """Extract PDF pages and store as child documents."""

    with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
        # Stream PDF to temp file
        for chunk in librarian_client.stream_document(doc_id):
            tmp.write(chunk)
        tmp.flush()

        # Extract pages
        reader = PdfReader(tmp.name)
        for page_num, page in enumerate(reader.pages, start=1):
            text = page.extract_text()

            # Store as child document
            child_id = f"{doc_id}-page-{page_num}"
            await librarian_client.add_child_document(
                parent_id=doc_id,
                document_id=child_id,
                kind="text/plain",
                title=f"Page {page_num}",
                content=text.encode('utf-8')
            )

            # Send to chunker queue
            await output_queue.send(child_id)
```

分块器接收这些子 ID，并以与处理用户上传的文本文档完全相同的方式处理它们。
如何处理用户上传的文本文档。

### 客户端更新

#### Python SDK

Python SDK (`trustgraph-base/trustgraph/api/library.py`) 应该能够透明地处理分块上传。公共接口保持不变：
分块上传。公共接口保持不变：

```python
# Existing interface - no change for users
library.add_document(
    id="doc-123",
    title="Large Report",
    kind="application/pdf",
    content=large_pdf_bytes,  # Can be hundreds of MB
    tags=["reports"]
)
```

内部，SDK 会检测文档大小并切换策略：

```python
class Library:
    CHUNKED_UPLOAD_THRESHOLD = 2 * 1024 * 1024  # 2MB

    def add_document(self, id, title, kind, content, tags=None, ...):
        if len(content) < self.CHUNKED_UPLOAD_THRESHOLD:
            # Small document: single operation (existing behavior)
            return self._add_document_single(id, title, kind, content, tags)
        else:
            # Large document: chunked upload
            return self._add_document_chunked(id, title, kind, content, tags)

    def _add_document_chunked(self, id, title, kind, content, tags):
        # 1. begin-upload
        session = self._begin_upload(
            document_metadata={...},
            total_size=len(content),
            chunk_size=5 * 1024 * 1024
        )

        # 2. upload-chunk for each chunk
        for i, chunk in enumerate(self._chunk_bytes(content, session.chunk_size)):
            self._upload_chunk(session.upload_id, i, chunk)

        # 3. complete-upload
        return self._complete_upload(session.upload_id)
```

**进度回调** (可选的增强功能)：

```python
def add_document(self, ..., on_progress=None):
    """
    on_progress: Optional callback(bytes_sent, total_bytes)
    """
```

这允许用户界面显示上传进度，而无需更改基本 API。

#### 命令行工具

**`tg-add-library-document`** 保持不变：

```bash
# Works transparently for any size - SDK handles chunking internally
tg-add-library-document --file large-report.pdf --title "Large Report"
```

可以添加可选的进度显示：

```bash
tg-add-library-document --file large-report.pdf --title "Large Report" --progress
# Output:
# Uploading: 45% (225MB / 500MB)
```

**已移除的旧工具：**

`tg-load-pdf` - 已过时，请使用 `tg-add-library-document`
`tg-load-text` - 已过时，请使用 `tg-add-library-document`

**管理员/调试命令**（可选，优先级较低）：

```bash
# List incomplete uploads (admin troubleshooting)
tg-add-library-document --list-pending

# Resume specific upload (recovery scenario)
tg-add-library-document --resume upload-abc-123 --file large-report.pdf
```

这些可能只是现有命令上的标志，而不是单独的工具。

#### API 规范更新

OpenAPI 规范 (`specs/api/paths/librarian.yaml`) 需要更新以下内容：

**新操作：**

`begin-upload` - 初始化分块上传会话
`upload-chunk` - 上传单个分块
`complete-upload` - 完成上传
`abort-upload` - 取消上传
`get-upload-status` - 查询上传进度
`list-uploads` - 列出用户未完成的上传
`stream-document` - 流式文档检索
`add-child-document` - 存储提取的文本（内部）
`list-children` - 列出子文档（管理员）

**修改后的操作：**

`list-documents` - 添加 `include-children` 参数

**新的模式：**

`ChunkedUploadBeginRequest`
`ChunkedUploadBeginResponse`
`ChunkedUploadChunkRequest`
`ChunkedUploadChunkResponse`
`UploadSession`
`UploadProgress`

**WebSocket 规范更新** (`specs/websocket/`)：

镜像 REST 操作以供 WebSocket 客户端使用，从而实现上传过程的实时
进度更新。

#### 用户体验注意事项

API 规范的更新可以实现前端改进：

**上传进度 UI：**
显示已上传分块的进度条
剩余预估时间
暂停/恢复功能

**错误恢复：**
中断的上传可以选择“恢复上传”
重新连接时，显示挂起的上传列表

**大型文件处理：**
客户端文件大小检测
大型文件的自动分块上传
长时间上传时提供清晰的反馈

这些用户体验改进需要前端工作，并由更新后的 API 规范提供指导。