LlamaIndex 系列【14】数据接入流水线（IngestionPipeline）

文章目录

• [1. 概述](#1. 概述)
• [2. 数据接入流水线](#2. 数据接入流水线)
• • [2.1 使用方式](#2.1 使用方式)
  • [2.2 对接向量数据库](#2.2 对接向量数据库)
  • [2.3 在流水线中生成向量嵌入](#2.3 在流水线中生成向量嵌入)
  • [2.4 缓存机制](#2.4 缓存机制)
  • • [2.4.1 本地缓存管理](#2.4.1 本地缓存管理)
    • [2.4.2 远端缓存管理](#2.4.2 远端缓存管理)
  • [2.5 异步支持](#2.5 异步支持)
  • [2.6 文档管理](#2.6 文档管理)
  • [2.7 并行处理](#2.7 并行处理)
  • [2.8 相关模块文档](#2.8 相关模块文档)
• [3. 转换组件](#3. 转换组件)
• • [3.1 使用方式](#3.1 使用方式)
  • [3.2 和索引结合使用](#3.2 和索引结合使用)
  • [3.3 自定义转换组件](#3.3 自定义转换组件)

1. 概述

数据接入流水线 （IngestionPipeline）是指 LlamaIndex 中专门用来把原始文档变成可检索 Node 的一站式处理链路。

里面每一步处理单元叫做转换组件 （Transformations），例如：文档切分器、元数据提取器、Embedding 向量化器都属于转换组件。

每一组「节点+转换组件」的处理结果都会被缓存。当缓存持久化后，后续再次运行相同节点与转换组合时，可以直接复用缓存结果，节省处理耗时。

想要查看 IngestionPipeline 的交互式示例，请参阅 RAG 命令行工具。

2. 数据接入流水线

2.1 使用方式

最简单的使用方式，实例化 IngestionPipeline：

from llama_index.core import Document
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.extractors import TitleExtractor
from llama_index.core.ingestion import IngestionPipeline, IngestionCache

# 构建流水线，配置转换组件
pipeline = IngestionPipeline(
    # transformations：转换组件链，按数组顺序串行执行
    transformations=[
        # 1.句子切分器：文档切割成Node节点，块大小25，块之间无重叠
        SentenceSplitter(chunk_size=25, chunk_overlap=0),
        # 2.标题提取器：从文本中提取标题，补充到节点metadata元数据
        TitleExtractor(),
        # 3.OpenAI向量嵌入：为每个Node文本计算embedding向量
        OpenAIEmbedding(),
    ]
)

# 执行流水线
nodes = pipeline.run(documents=[Document.example()])

实际业务场景中，文档一般来自 SimpleDirectoryReader 或者 Llama Hub 的其他读取器。

2.2 对接向量数据库

运行流水线时，可以配置向量存储，处理完成的节点会自动写入远端向量库。后续可以基于该向量库构建索引。

from llama_index.core import Document
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.extractors import TitleExtractor
from llama_index.core.ingestion import IngestionPipeline
from llama_index.vector_stores.qdrant import QdrantVectorStore

import qdrant_client

# 实例化Qdrant客户端，:memory: 代表内存模式，进程销毁数据就丢失，仅用于测试
client = qdrant_client.QdrantClient(location=":memory:")

# 封装为LlamaIndex的向量存储对象，绑定客户端和集合名称
vector_store = QdrantVectorStore(client=client, collection_name="test_store")

# 构建数据接入流水线，增加vector_store参数
pipeline = IngestionPipeline(
    transformations=[
        # 文档切分：块大小25，无重叠
        SentenceSplitter(chunk_size=25, chunk_overlap=0),
        # 提取标题元数据，存入node.metadata
        TitleExtractor(),
        # 为每个节点生成OpenAI向量embedding
        OpenAIEmbedding(),
    ],
    # 指定向量库：流水线run()执行完成后，Node会自动写入Qdrant，无需手动插入
    vector_store=vector_store,
)

# 直接把数据写入向量库
pipeline.run(documents=[Document.example()])

# 基于向量库创建索引
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_vector_store(vector_store)

2.3 在流水线中生成向量嵌入

上面示例中，向量嵌入是流水线的其中一个处理环节。

如果流水线对接向量库，向量嵌入计算必须放在流水线中，否则后续构建索引会报错。

如果不对接向量库，仅需要输出节点列表，则可以省略向量嵌入环节。

2.4 缓存机制

IngestionPipeline 会对每一组「节点+转换组件」做哈希并缓存，重复处理相同数据时可以提速。

2.4.1 本地缓存管理

流水线支持缓存持久化保存与加载。

# 持久化缓存到本地
pipeline.persist("./pipeline_storage")

# 加载恢复缓存
new_pipeline = IngestionPipeline(
    transformations=[
        SentenceSplitter(chunk_size=25, chunk_overlap=0),
        TitleExtractor(),
    ],
)
new_pipeline.load("./pipeline_storage")

# 读取缓存，瞬间完成执行
nodes = pipeline.run(documents=[Document.example()])

缓存体积过大时，可以清空缓存：

# 清空全部缓存内容
cache.clear()

2.4.2 远端缓存管理

支持多种远端存储作为缓存后端：

• RedisCache
• MongoDBCache
• FirestoreCache

RedisCache 使用示例：

from llama_index.core import Document
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.extractors import TitleExtractor
from llama_index.core.ingestion import IngestionPipeline, IngestionCache
from llama_index.storage.kvstore.redis import RedisKVStore as RedisCache

ingest_cache = IngestionCache(
    cache=RedisCache.from_host_and_port(host="127.0.0.1", port=6379),
    collection="my_test_cache",
)

pipeline = IngestionPipeline(
    transformations=[
        SentenceSplitter(chunk_size=25, chunk_overlap=0),
        TitleExtractor(),
        OpenAIEmbedding(),
    ],
    cache=ingest_cache,
)

# 直接写入向量库，数据自动存入远端缓存
nodes = pipeline.run(documents=[Document.example()])

使用远端缓存无需手动调用 persist，处理过程自动写入指定远端集合。

2.5 异步支持

IngestionPipeline 支持异步执行：

nodes = await pipeline.arun(documents=documents)

2.6 文档管理

为流水线绑定 docstore（文档存储），即可开启文档去重管理能力。

流水线以 document.doc_id、node.ref_doc_id 作为标识，自动检测重复文档。

工作原理：

• 维护 doc_id → document_hash 的映射关系
• 绑定向量库时：
  • 检测到相同 doc_id，文档哈希发生变化：重新处理文档并更新写入
  • 检测到相同 doc_id，文档哈希无变化：跳过该节点
• 未绑定向量库时：
  • 校验全部节点的已有哈希
  • 命中重复则跳过节点
  • 无重复则正常处理

注意：不绑定向量库，仅能做输入数据的去重过滤。

from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.storage.docstore import SimpleDocumentStore

pipeline = IngestionPipeline(
    transformations=[...], docstore=SimpleDocumentStore()
)

完整示例 Notebook：文档管理流水线

参考教程：基于 Redis 完整接入链路

2.7 并行处理

run 方法支持多进程并行，底层基于 multiprocessing.Pool，将节点批次分发到多个处理器。

设置 num_workers 指定进程数量开启并行：

from llama_index.core.ingestion import IngestionPipeline

pipeline = IngestionPipeline(
    transformations=[...],
)
pipeline.run(documents=[...], num_workers=4)

2.8 相关模块文档

• 转换组件指南
• 高级接入流水线
• 异步接入流水线
• 文档管理流水线
• Redis 接入流水线
• Google Drive 接入流水线
• 并行执行流水线

---

3. 转换组件

转换组件（Transformation）接收节点列表作为输入，输出处理后的节点列表。

所有实现 Transformation 基类的组件，同时提供同步 __call__() 和异步 acall() 接口。

以下组件均属于转换组件：

• TextSplitter 文本切分器
• NodeParser 节点解析器
• MetadataExtractor 元数据提取器
• Embeddings 向量嵌入模型（查看支持的嵌入模型列表）

3.1 使用方式

转换组件最常搭配 IngestionPipeline 使用，也可以直接调用。

from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.extractors import TitleExtractor

node_parser = SentenceSplitter(chunk_size=512)
extractor = TitleExtractor()

# 直接调用转换组件
nodes = node_parser(documents)

# 异步调用转换组件
nodes = await extractor.acall(nodes)

3.2 和索引结合使用

转换组件可以传入索引，或者配置全局设置；调用索引的 from_documents()、insert() 时会自动执行转换。

from llama_index.core import VectorStoreIndex
from llama_index.core.extractors import (
    TitleExtractor,
    QuestionsAnsweredExtractor,
)
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.node_parser import TokenTextSplitter

transformations = [
    TokenTextSplitter(chunk_size=512, chunk_overlap=128),
    TitleExtractor(nodes=5),
    QuestionsAnsweredExtractor(questions=3),
]

# 全局配置
from llama_index.core import Settings
Settings.transformations = [text_splitter, title_extractor, qa_extractor]

# 单索引独立配置
index = VectorStoreIndex.from_documents(
    documents, transformations=transformations
)

3.3 自定义转换组件

继承基类即可实现自定义转换逻辑。

自定义组件，清除文本中的特殊字符与标点符号，示例：

import re
from llama_index.core import Document
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.schema import TransformComponent


class TextCleaner(TransformComponent):
    def __call__(self, nodes, **kwargs):
        for node in nodes:
            node.text = re.sub(r"[^0-9A-Za-z ]", "", node.text)
        return nodes

自定义组件可以直接调用，也可以放入接入流水线：

# 在流水线中使用自定义转换
pipeline = IngestionPipeline(
    transformations=[
        SentenceSplitter(chunk_size=25, chunk_overlap=0),
        TextCleaner(),
        OpenAIEmbedding(),
    ],
)

nodes = pipeline.run(documents=[Document.example()])

---