项目实践｜ETL Pipeline 完整解析：从多源文档到向量库的全链路实现

在RAG（检索增强生成）项目中，"数据"是核心基石------无论是PDF、Word等本地文档，还是URL网页、飞书文档、S3云存储文件，都需要经过一套标准化流程处理，才能转化为可被检索的向量数据，存入向量数据库。这套连接"原始文档"与"向量库"的核心链路，就是ETL Pipeline。

ETL（Extract-Transform-Load）即提取、转换、加载，看似是数据领域的经典概念，但在RAG项目中，其落地逻辑有着鲜明的场景特性：需要适配多源文档、支持灵活的节点编排、保证数据处理的幂等性与高效性。本文结合我们的RAG项目实践，从流程概述、节点实现、编排配置、执行引擎到实际应用，全方位拆解ETL Pipeline的全链路实现，分享项目中遇到的问题与优化思路。

一、ETL Pipeline 核心定位：RAG项目的数据"预处理中枢"

在RAG项目中，ETL Pipeline的核心目标是：将分散、异构的多源文档，通过标准化的步骤，转化为结构统一、可嵌入向量、支持高效检索的文本块，最终写入向量数据库（我们项目中使用Milvus），为后续的检索与生成提供高质量的数据支撑。

与传统ETL（主要用于数据仓库同步）不同，我们项目中的ETL Pipeline有三个核心特点：

多源适配：支持本地文件、HTTP URL、AWS S3、飞书文档等多种来源，解决企业中"文档分散存储"的痛点；
轻量灵活：采用节点化设计，支持自定义节点编排，可根据不同文档类型（如PDF、Markdown）配置不同的处理流程；
适配RAG：所有处理步骤围绕"向量生成"展开，重点解决文本解析、分块、增强等关键问题，确保生成的向量能精准匹配检索需求。

其核心流程可简化为：

bash 复制代码

文档输入 → 提取(Extract) → 转换(Transform) → 加载(Load) → 向量库

看似简单的四步，背后却包含了五大核心节点的协同工作，以及灵活的编排与执行逻辑------这也是我们项目落地ETL Pipeline的重点与难点。

二、项目文件结构：节点化设计，解耦清晰

为了实现"灵活编排、易于扩展"的目标，我们将ETL Pipeline相关代码按"领域模型-节点-引擎-服务"分层设计，核心文件结构如下（对应项目实际代码路径），确保各模块权责清晰、可维护性强：

bash 复制代码

bootstrap/src/main/java/com/nageoffer/ai/ragent/ingestion/
├── domain/                  # 领域模型：定义核心数据结构
│   ├── pipeline/
│   │   ├── PipelineDefinition.java    # 管道定义（整体流程配置）
│   │   └── NodeConfig.java            # 节点配置（单个节点的参数、条件等）
│   ├── context/
│   │   └── IngestionContext.java      # 执行上下文（传递数据、日志）
│   └── result/
│       └── NodeResult.java            # 节点执行结果（状态、信息）
│
├── node/                    # 核心节点：ETL各步骤的具体实现
│   ├── IngestionNode.java            # 节点接口（统一所有节点的规范）
│   ├── FetcherNode.java              # 提取节点（Extract阶段核心）
│   ├── ParserNode.java                # 解析节点（Transform阶段-解析）
│   ├── ChunkerNode.java              # 分块节点（Transform阶段-分块）
│   ├── EnricherNode.java             # 增强节点（Transform阶段-增强）
│   └── IndexerNode.java              # 索引节点（Load阶段核心）
│
├── engine/                  # 执行引擎：负责管道的调度与执行
│   ├── IngestionEngine.java          # 管道执行引擎（链式执行、条件判断）
│   └── ConditionEvaluator.java        # 条件评估器（判断节点是否执行）
│
└── service/                 # 业务服务：对外提供管道调用接口
    └── IngestionPipelineServiceImpl.java  # 管道服务（封装引擎调用）

这种分层设计的核心优势的是：新增文档来源、修改处理逻辑时，只需修改对应节点或配置，无需改动核心引擎，极大提升了项目的可扩展性。例如，后续我们需要新增"阿里云OSS文档提取"功能，只需新增一个OSSFetcher实现类，无需修改FetcherNode的核心逻辑。

三、ETL Pipeline 完整流程：从文档输入到向量入库的全链路

结合我们项目的实际业务场景，ETL Pipeline的完整流程分为三大阶段（Extract、Transform、Load），包含五个核心节点，每个节点各司其职、协同工作，确保数据处理的准确性与高效性。以下是完整流程拆解（对应项目实际执行逻辑）：

3.1 流程概览（可视化拆解）

bash 复制代码

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ETL Pipeline 完整流程                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────┐                                                          │
│  │   文档输入    │  ← PDF/Word/Excel/HTML/URL/飞书/本地文件/S3              │
│  └──────┬───────┘                                                          │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  阶段1: Extract（提取）                                               │  │
│  │  ┌────────────────┐                                                   │  │
│  │  │  FetcherNode   │  ← 从多种来源获取原始字节                         │  │
│  │  │  (获取节点)     │  • LocalFileFetcher (本地文件)                   │  │
│  │  │                │  • HttpUrlFetcher (HTTP URL)                     │  │
│  │  │                │  • S3Fetcher (AWS S3)                             │  │
│  │  │                │  • FeishuFetcher (飞书文档)                       │  │
│  │  └────────────────┘                                                   │  │
│  │              ↓ rawBytes                                               │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  阶段2: Transform - Part 1（转换 - 解析）                             │  │
│  │  ┌────────────────┐                                                   │  │
│  │  │  ParserNode    │  ← 将字节流解析为结构化文本                        │  │
│  │  │  (解析节点)     │  • Apache Tika (PDF/Word/Excel)                  │  │
│  │  │                │  • Markdown Parser                                 │  │
│  │  │                │  • HTML Parser                                     │  │
│  │  └────────────────┘                                                   │  │
│  │              ↓ rawText / StructuredDocument                            │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  阶段2: Transform - Part 2（转换 - 增强）                             │  │
│  │  ┌────────────────┐                                                   │  │
│  │  │  EnricherNode   │  ← LLM 增强：提取关键词/摘要/元数据               │  │
│  │  │  (增强节点)     │  • 关键词提取                                     │  │
│  │  │                │  • 摘要生成                                       │  │
│  │  │                │  • 元数据补充                                     │  │
│  │  └────────────────┘                                                   │  │
│  │              ↓ enhancedText / enrichedMetadata                         │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  阶段2: Transform - Part 3（转换 - 分块）                             │  │
│  │  ┌────────────────┐                                                   │  │
│  │  │  ChunkerNode   │  ← 按策略切分成多个文本块                         │  │
│  │  │  (分块节点)     │  • FixedSizeChunker (固定大小)                   │  │
│  │  │                │  • RecursiveChunker (递归字符分割)               │  │
│  │  │                │  • SemanticChunker (语义分割)                    │  │
│  │  └────────────────┘                                                   │  │
│  │              ↓ List<VectorChunk>                                       │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  阶段3: Load（加载）                                                 │  │
│  │  ┌────────────────┐                                                   │  │
│  │  │  IndexerNode   │  ← 生成向量并写入向量数据库                        │  │
│  │  │  (索引节点)     │  • Embedding 生成                                 │  │
│  │  │                │  • Milvus 写入                                     │  │
│  │  └────────────────┘                                                   │  │
│  │              ↓ VectorSpace                                             │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────┐                                                          │
│  │   完成 ✅     │  ← 文档已存入向量数据库，可供 RAG 检索                  │
│  └──────────────┘                                                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

3.2 流程核心说明

整个流程的核心是"数据流转"------通过IngestionContext（执行上下文），将上一个节点的输出作为下一个节点的输入，全程传递原始字节、文本、分块等数据，同时记录每个节点的执行日志，便于问题排查。

其中，Transform阶段是整个Pipeline的核心，分为解析、增强、分块三个子步骤，也是我们项目中优化最多的部分------因为不同类型的文档（如PDF扫描件、Markdown文档），其解析和分块逻辑差异较大，需要针对性适配。

四、核心节点详解：每个节点的实现逻辑与项目实践

所有节点都实现了IngestionNode接口，统一了"getNodeType（节点类型）"和"execute（执行逻辑）"两个核心方法，确保执行引擎能统一调度。以下结合项目源码和实际应用，拆解每个节点的核心实现、功能特点及优化细节。

4.1 FetcherNode（提取节点）：多源文档的"入口"

FetcherNode是ETL Pipeline的第一个节点，核心职责是"从不同来源获取原始文档字节流"，解决"多源文档统一接入"的问题。其核心源码如下（简化后，保留核心逻辑）：

java 复制代码

// node/FetcherNode.java
@Component
public class FetcherNode implements IngestionNode {

    @Override
    public String getNodeType() {
        return IngestionNodeType.FETCHER.getValue();  // "fetcher"
    }

    @Override
    public NodeResult execute(IngestionContext context, NodeConfig config) {
        // 1. 幂等性校验：如果已有原始字节，直接跳过（避免重复获取）
        if (context.getRawBytes() != null) {
            return NodeResult.ok("已跳过：原始字节已存在");
        }

        // 2. 获取文档来源信息（从上下文获取，由前端传入）
        DocumentSource source = context.getSource();

        // 3. 策略模式：根据来源类型选择对应的Fetcher实现
        DocumentFetcher fetcher = fetchers.get(source.getType());

        // 4. 执行获取操作，获取原始字节和MIME类型
        FetchResult result = fetcher.fetch(source);

        // 5. 将结果存入上下文，供下一个节点使用
        context.setRawBytes(result.content());
        context.setMimeType(result.mimeType());

        return NodeResult.ok("已获取 " + result.content().length + " 字节");
    }
}

项目实践重点

策略模式的应用：我们定义了DocumentFetcher接口，不同来源（本地文件、URL、S3、飞书）对应不同的实现类，通过工厂模式获取对应Fetcher，后续新增来源只需新增实现类，无需修改核心代码；
幂等性设计：这是项目中非常关键的优化------在实际场景中，可能出现管道重试的情况，幂等性确保重复执行时不会重复获取文档，避免资源浪费和数据冗余；
MIME类型自动检测：获取文档时自动检测文件类型（如application/pdf、text/markdown），为后续解析节点提供依据。

支持的来源类型

Fetcher实现类	文档来源	项目中的实际用途
LocalFileFetcher	本地文件	支持用户上传PDF、Word等本地文档
HttpUrlFetcher	HTTP URL	抓取网页内容，用于获取公开的行业资讯
S3Fetcher	AWS S3	对接企业云存储，获取批量文档
FeishuFetcher	飞书文档	对接企业飞书，获取内部知识库文档

4.2 ParserNode（解析节点）：字节流到文本的"转换桥梁"

FetcherNode获取到原始字节流后，需要通过ParserNode解析为结构化文本------这是后续所有处理的基础。我们项目中使用Apache Tika作为核心解析库，支持多种格式文档的统一解析，核心源码如下：

java 复制代码

// node/ParserNode.java
@Component
public class ParserNode implements IngestionNode {

    @Override
    public String getNodeType() {
        return IngestionNodeType.PARSER.getValue();  // "parser"
    }

    @Override
    public NodeResult execute(IngestionContext context, NodeConfig config) {
        // 1. 获取上一个节点传入的原始字节
        byte[] rawBytes = context.getRawBytes();

        // 2. 检测MIME类型（若上一步未检测，此处补充检测）
        String mimeType = context.getMimeType();
        if (mimeType == null) {
            mimeType = MimeTypeDetector.detect(rawBytes, fileName);
        }

        // 3. 解析节点配置（如支持的MIME类型）
        ParserSettings settings = parseSettings(config.getSettings());

        // 4. 选择解析器（默认使用Apache Tika，支持多格式）
        DocumentParser parser = parserSelector.select(ParserType.TIKA.getType());

        // 5. 执行解析，获取文本和元数据
        ParseResult result = parser.parse(rawBytes, mimeType, options);

        // 6. 将解析结果存入上下文
        context.setRawText(result.text());
        context.setDocument(StructuredDocument.builder()
                .text(result.text())
                .metadata(result.metadata())
                .build());

        return NodeResult.ok("解析文本长度=" + result.text().length());
    }
}

项目实践重点

Apache Tika的优势：统一解析PDF、Word、Excel、HTML、Markdown等多种格式，无需为每种格式单独开发解析逻辑，极大降低了开发成本；
元数据提取：除了解析文本，还会提取文档的元数据（如标题、作者、创建时间、文件大小），这些元数据会后续用于文本增强和检索过滤；
异常处理：针对解析失败的场景（如加密PDF、损坏文件），会返回明确的错误信息，并记录日志，便于运维排查。

4.3 EnricherNode（增强节点）：提升文本检索质量的"关键一步"

解析后的原始文本可能存在信息杂乱、关键词不明确的问题，EnricherNode通过调用大模型（LLM），对文本进行增强处理，提取关键词、生成摘要、补充元数据，提升后续向量检索的准确性。核心源码如下：

java 复制代码

// node/EnricherNode.java
@Component
public class EnricherNode implements IngestionNode {

    @Override
    public String getNodeType() {
        return IngestionNodeType.ENRICHER.getValue();  // "enricher"
    }

    @Override
    public NodeResult execute(IngestionContext context, NodeConfig config) {
        // 获取分块列表（若未分块，先使用原始文本）
        List<VectorChunk> chunks = context.getChunks();
        EnricherSettings settings = parseSettings(config.getSettings());

        // 获取增强任务（可配置：关键词提取、摘要生成、元数据补充）
        List<EnricherTask> tasks = settings.getTasks();

        for (VectorChunk chunk : chunks) {
            // 构建Prompt，引导LLM提取指定信息
            ChatRequest request = ChatRequest.builder()
                    .messages(List.of(
                            ChatMessage.system(enricherPrompt),
                            ChatMessage.user(chunk.getContent())
                    ))
                    .build();

            // 调用LLM获取响应
            String response = chatClient.chat(request);

            // 解析LLM响应，提取增强信息
            Map<String, Object> enriched = parseResponse(response);

            // 将增强信息追加到分块的元数据中
            chunk.getMetadata().putAll(enriched);
        }

        return NodeResult.ok("已增强 " + chunks.size() + " 个 chunk");
    }
}

项目实践重点

可配置增强任务：支持通过配置指定增强任务（如只提取关键词、只生成摘要，或两者都做），适配不同场景的需求；
分块增强：在分块后对每个文本块进行单独增强，确保每个块的关键词和摘要都贴合自身内容，避免全局增强导致的信息偏差；
性能优化：针对大量分块的场景，我们引入了批量调用LLM的逻辑，减少接口调用次数，提升增强效率。

4.4 ChunkerNode（分块节点）：适配向量检索的"核心优化"

RAG项目中，文本分块是影响检索效果的关键因素------分块过大，会导致检索时精准度不足；分块过小，会导致上下文丢失。ChunkerNode通过多种分块策略，将解析后的文本切分为大小合适的文本块（VectorChunk），核心源码如下：

java 复制代码

// node/ChunkerNode.java
@Component
public class ChunkerNode implements IngestionNode {

    @Override
    public String getNodeType() {
        return IngestionNodeType.CHUNKER.getValue();  // "chunker"
    }

    @Override
    public NodeResult execute(IngestionContext context, NodeConfig config) {
        // 1. 获取文本（优先使用增强后的文本，若无则使用原始文本）
        String text = StringUtils.hasText(context.getEnhancedText())
                ? context.getEnhancedText()
                : context.getRawText();

        // 2. 解析分块配置（策略、块大小、重叠度等）
        ChunkerSettings settings = parseSettings(config.getSettings());

        // 3. 选择分块策略（通过工厂模式获取）
        ChunkingStrategy chunker = chunkingStrategyFactory
                .requireStrategy(settings.getStrategy());

        // 4. 配置分块参数（块大小、重叠度、分隔符）
        ChunkingOptions options = ChunkingOptions.builder()
                .chunkSize(settings.getChunkSize())
                .overlapSize(settings.getOverlapSize())
                .separator(settings.getSeparator())
                .build();

        // 5. 执行分块，将结果存入上下文
        List<VectorChunk> chunks = chunker.chunk(text, options);
        context.setChunks(chunks);

        return NodeResult.ok("已分块 " + chunks.size() + " 段");
    }
}

分块策略对比（项目实践总结）

分块策略	核心说明	项目中的适用场景
FixedSizeChunker（固定大小）	按固定字数分块，简单高效	简单文本、日志类文档（结构简单，无复杂语义）
RecursiveChunker（递归字符分割）	按换行、空格等分隔符递归分割，优先保证语义完整	通用文档（如Word、Markdown，有明确的段落结构）
SemanticChunker（语义分割）	基于文本语义相似度分块，确保每个块的语义连贯	复杂文档（如PDF论文、技术文档，语义关联性强）

项目优化点：重叠度配置

我们在分块时引入了"重叠度（overlapSize）"配置，默认重叠50个字符------这样可以避免因分块导致的上下文断裂，例如"某段文字的结尾和下一段的开头"有语义关联，重叠部分可以确保检索时能完整匹配上下文。

4.5 IndexerNode（索引节点）：文本到向量的"最终一步"

IndexerNode是ETL Pipeline的最后一个节点，核心职责是将分块后的文本（VectorChunk）生成向量嵌入（Embedding），并写入向量数据库（我们项目中使用Milvus），完成整个数据处理流程。核心源码如下：

java 复制代码

// node/IndexerNode.java
@Component
public class IndexerNode implements IngestionNode {

    @Override
    public String getNodeType() {
        return IngestionNodeType.INDEXER.getValue();  // "indexer"
    }

    @Override
    public NodeResult execute(IngestionContext context, NodeConfig config) {
        // 1. 获取分块列表
        List<VectorChunk> chunks = context.getChunks();

        // 2. 解析索引配置（向量库集合名称、嵌入模型等）
        IndexerSettings settings = parseSettings(config.getSettings());
        String collectionName = settings.getCollectionName();

        // 3. 确保向量库集合存在（不存在则自动创建）
        vectorStoreAdmin.ensureCollection(collectionName, dimension);

        // 4. 调用Embedding API，生成向量（批量处理）
        float[][] vectors = generateEmbeddings(chunks);

        // 5. 将向量和分块数据批量写入Milvus
        InsertResp resp = milvusClient.insert(InsertReq.builder()
                .collectionName(collectionName)
                .vectors(vectors)
                .data(records)
                .build());

        return NodeResult.ok("已索引 " + chunks.size() + " 个 chunk");
    }
}

项目实践重点

向量库自动管理：通过vectorStoreAdmin.ensureCollection方法，自动创建向量库集合（Collection），无需手动操作，降低运维成本；
批量处理：向量生成和写入都采用批量模式，提升处理效率------例如，一次处理100个分块，批量生成向量并写入Milvus，避免单条处理的性能瓶颈；
嵌入模型适配：支持配置不同的Embedding模型（如text-embedding-ada-002、m3e-base），可根据检索精度和性能需求灵活切换。

五、节点编排与执行引擎：灵活调度的核心

我们项目中的ETL Pipeline支持"自定义节点编排"------通过配置文件，可灵活调整节点的执行顺序、执行条件，适配不同类型的文档处理需求。这背后依赖于"节点编排配置"和"执行引擎"的协同工作。

5.1 核心配置模型

节点配置（NodeConfig）

每个节点的配置信息，包括节点ID、类型、参数、执行条件、下一个节点ID，核心代码如下：

java 复制代码

// domain/pipeline/NodeConfig.java
@Data
@Builder
public class NodeConfig {
    /** 节点唯一标识 */
    private String nodeId;
    /** 节点类型（fetcher/parser/enricher/chunker/indexer） */
    private String nodeType;
    /** 节点配置参数（如分块大小、增强任务） */
    private JsonNode settings;
    /** 执行条件（满足条件才执行该节点） */
    private JsonNode condition;
    /** 下一个节点ID（串联节点，形成执行链路） */
    private String nextNodeId;
}

管道定义（PipelineDefinition）

一个完整的Pipeline由多个NodeConfig组成，按执行顺序排列，核心代码如下：

java 复制代码

// domain/pipeline/PipelineDefinition.java
@Data
@Builder
public class PipelineDefinition {
    private String id;          // 管道唯一标识
    private String name;        // 管道名称（如PDF文档摄取管道）
    private String description; // 管道描述
    private List<NodeConfig> nodes; // 按执行顺序排列的节点列表
}

数据库存储

为了便于管理和复用，我们将管道配置和节点配置存入数据库，核心表结构如下：

java 复制代码

-- 管道定义表
CREATE TABLE t_ingestion_pipeline (
    id          bigint(20) NOT NULL,
    name        varchar(100) NOT NULL,  -- 管道名称
    description text,                  -- 管道描述
    created_by  varchar(64),           -- 创建人
    create_time datetime,              -- 创建时间
    PRIMARY KEY (id)
);

-- 节点配置表（关联管道）
CREATE TABLE t_ingestion_pipeline_node (
    id             bigint(20) NOT NULL,
    pipeline_id    bigint(20) NOT NULL,  -- 所属管道ID
    node_id        varchar(64) NOT NULL,  -- 节点标识
    node_type      varchar(30) NOT NULL,  -- 节点类型
    next_node_id   varchar(64),            -- 下一个节点ID
    settings_json  json,                   -- 节点配置参数（JSON格式）
    condition_json json,                  -- 执行条件（JSON格式）
    PRIMARY KEY (id)
);

5.2 执行引擎（IngestionEngine）

IngestionEngine是Pipeline的"调度核心"，负责解析管道配置、验证管道合法性、链式执行节点，核心源码如下（简化）：

java 复制代码

// engine/IngestionEngine.java
@Slf4j
@Component
public class IngestionEngine {

    /** 执行整个管道 */
    public IngestionContext execute(PipelineDefinition pipeline, 
                                     IngestionContext context) {
        // 1. 构建节点映射（nodeId → NodeConfig），便于快速查找
        Map<String, NodeConfig> nodeConfigMap = buildNodeConfigMap(pipeline.getNodes());

        // 2. 验证管道（检测是否存在环、起始节点是否唯一）
        validatePipeline(nodeConfigMap);

        // 3. 找到起始节点（没有前序节点的节点）
        String startNodeId = findStartNode(nodeConfigMap);

        // 4. 链式执行所有节点
        executeChain(startNodeId, nodeConfigMap, context);

        return context;
    }

    /** 链式执行节点 */
    private void executeChain(String nodeId, Map<String, NodeConfig> configMap,
                               IngestionContext context) {
        while (nodeId != null) {
            NodeConfig config = configMap.get(nodeId);
            // 根据节点类型获取对应的节点实现
            IngestionNode node = nodeMap.get(config.getNodeType());

            // 检查执行条件（满足条件才执行）
            if (conditionEvaluator.evaluate(config.getCondition(), context)) {
                NodeResult result = node.execute(context, config);
                // 记录执行日志
                context.getLogs().add(buildNodeLog(config, result));
            }

            // 切换到下一个节点
            nodeId = config.getNextNodeId();
        }
    }
}

核心功能说明

管道验证：检测管道是否存在环（如节点A→节点B→节点A），避免死循环；检测起始节点是否唯一，确保执行入口清晰；
条件执行：支持通过配置条件表达式，控制节点是否执行。例如，只有当文档类型为PDF时，才执行某一特定的解析节点；
日志记录：每个节点的执行结果（成功/失败、执行信息）都会存入上下文日志，便于问题排查和流程追溯。

六、项目配置示例：PDF文档摄取管道

以下是我们项目中最常用的"PDF文档摄取管道"的JSON配置示例，结合实际业务场景，配置了完整的节点链路和参数，可直接复用或修改：

bash 复制代码

{
  "id": "pipeline-001",
  "name": "PDF文档摄取管道",
  "nodes": [
    {
      "nodeId": "fetcher-1",
      "nodeType": "fetcher",
      "nextNodeId": "parser-1",
      "settings": {
        "sourceType": "local"  // 来源类型：本地文件
      }
    },
    {
      "nodeId": "parser-1",
      "nodeType": "parser",
      "nextNodeId": "enricher-1",
      "settings": {
        "mimeTypes": ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"]
      }
    },
    {
      "nodeId": "enricher-1",
      "nodeType": "enricher",
      "nextNodeId": "chunker-1",
      "settings": {
        "tasks": [
          {"type": "keyword", "maxCount": 5},  // 提取最多5个关键词
          {"type": "summary", "maxLength": 200} // 生成最多200字摘要
        ]
      }
    },
    {
      "nodeId": "chunker-1",
      "nodeType": "chunker",
      "nextNodeId": "indexer-1",
      "settings": {
        "strategy": "recursive",  // 分块策略：递归字符分割
        "chunkSize": 512,         // 块大小：512字符
        "overlapSize": 50,        // 重叠度：50字符
        "separator": "\n\n"       // 分隔符：空行
      }
    },
    {
      "nodeId": "indexer-1",
      "nodeType": "indexer",
      "settings": {
        "collectionName": "knowledge_base",  // 向量库集合名称
        "embeddingModel": "text-embedding-ada-002"  // Embedding模型
      }
    }
  ]
}

配置说明

节点	关键配置	实际作用
fetcher	sourceType: local	处理用户上传的本地PDF、Word文档
parser	mimeTypes	只解析PDF和Word格式，避免无效文档
enricher	tasks	提取关键词和摘要，提升检索精度
chunker	strategy、chunkSize、overlapSize	按段落分割PDF文本，确保语义完整
indexer	collectionName、embeddingModel	将向量写入指定集合，使用适配的Embedding模型

七、数据流与项目优化总结

7.1 核心数据流（IngestionContext）

整个ETL Pipeline的数据流转，都通过IngestionContext（执行上下文）实现，其核心数据结构如下，记录了从原始字节到向量入库的全流程数据：

bash 复制代码

IngestionContext
       │
       ├── source: DocumentSource      ← 文档来源信息（路径、类型等）
       ├── rawBytes: byte[]            ← FetcherNode提取的原始字节
       ├── mimeType: String            ← 文档MIME类型
       ├── rawText: String            ← ParserNode解析后的原始文本
       ├── enhancedText: String       ← EnricherNode增强后的文本
       ├── document: StructuredDocument ← 结构化文档（文本+元数据）
       ├── chunks: List<VectorChunk>   ← ChunkerNode分块后的文本块
       └── logs: List<NodeLog>        ← 所有节点的执行日志

7.2 项目实践总结与优化方向

核心收获

节点化设计提升扩展性：通过统一的IngestionNode接口，新增节点、修改节点逻辑无需改动核心引擎，适配多场景需求；
标准化流程提升可维护性：统一的ETL流程，让不同开发者都能快速理解数据处理逻辑，便于问题排查和迭代；
灵活编排提升适配性：通过配置文件即可调整节点链路，适配不同类型的文档处理需求，无需硬编码。

后续优化方向

节点并行执行：目前采用链式串行执行，后续可支持无依赖节点的并行执行（如解析和增强可并行），提升处理效率；
分块策略自适应：根据文档类型自动选择分块策略（如PDF自动使用递归分割，网页自动使用语义分割）；
监控告警：新增Pipeline执行监控，统计处理耗时、成功率，当出现失败时触发告警，提升运维效率；
缓存优化：对常用的文档解析结果、向量数据进行缓存，避免重复处理，提升性能。

八、最后

在RAG项目中，ETL Pipeline看似是"基础环节"，却直接决定了向量数据的质量，进而影响整个RAG系统的检索和生成效果。我们通过节点化设计、灵活编排、标准化流程，实现了多源文档的高效处理，解决了企业中"文档分散、格式多样、检索困难"的痛点。

本文结合项目源码和实际落地经验，详细拆解了ETL Pipeline的全链路实现，希望能为正在做RAG、数据摄取相关项目的开发者提供参考。ETL的核心不是"提取、转换、加载"这三个单词，而是"标准化、可扩展、高效性"------只有做好这三点，才能让数据真正成为RAG项目的核心竞争力。