Eino 组件核心篇：文档进入 RAG 前，Loader 和 Parser 的职责划分

它说明 Loader 的目标从来不是'把内容读出来就算完'，而是'把内容整理成系统认可的文档协议再交出去'。

再看 src Source。

Source 现在只有一个 URI 字段，设计得很克制。
这个做法的好处是，它把'来源描述'压成了一个统一入口：

• 本地文件路径可以是 URI
• 网络 URL 可以是 URI
• 存储系统对象地址也可以是 URI

这其实是在提醒你：Loader 关注的是'统一来源标识'，不是给每种来源单独造一套接口。

最后看 opts ...LoaderOption。

官方没有给 Loader 设计一套很重的公共参数表，而是把公共层保持极简，把可变部分留给各个具体实现。

这代表的不是'设计不完整'，恰恰相反，它说明官方很清楚这层该怎么收：

• 公共协议统一
• 具体实现差异下放
• 运行时扩展通过 Option 接进去

所以这段接口真正表达的是：

Loader 要统一的是调用姿势和输出协议，不是把所有来源都塞进一个笨重的大接口里。

3. Source 和 schema.Document 为什么是这条链路的关键协议

如果说 Load 是入口方法，那 Source 和 schema.Document 才是整条文档链路真正的协议地基。

Source 看起来简单，但 URI 的意义其实比'文件路径'大得多。

它不只告诉 Loader 去哪里取内容，也会影响后面的解析策略。
尤其当你接 ExtParser 这类'基于扩展名选择解析器'的实现时，URI 不只是来源地址，它还是格式判断线索。

再看 schema.Document：

type Document struct {
	ID       string
	Content  string
	MetaData map[string]any
}

这三个字段里，很多人最容易低估的是 MetaData。

可在工程里，MetaData 根本不是附赠字段，它几乎就是后续链路的挂载点。

它至少承载这些信息：

• 文档来源
• 原始 URI
• 文件扩展名
• 页码、分段、子索引
• 向量、分数、排序相关信息
• 其他业务自定义字段

你现在如果把 MetaData 看轻，后面通常会在三个地方吃亏：

• 来源追踪：查到一段内容，却不知道它从哪来的
• 排序和召回：拿到了文档，却缺少分数、层级、子索引等附加信息
• 链路排障：内容不对，却没法判断是 Loader 问题、Parser 问题，还是后处理问题

所以别把 Document 理解成'内容字符串 + 一个 map'。

在 Eino 里，它更像是文档在系统里的统一载体。
Content 是正文，MetaData 是上下文，二者缺一不可。

4. 为什么 Parser 不是配角，而是 Loader 内部真正的内容解释层

很多人学到 Loader 这一层时，会把注意力都放在'怎么读 URL''怎么读文件'上。

可只要你继续往下一看，就会发现真正决定文档质量的，往往不是'读到了没有'，而是'读到以后怎么解释'。

这就是 Parser 的职责。

官方接口同样很短：

type Parser interface {
	Parse(ctx context.Context, reader io.Reader, opts ...Option) ([]*schema.Document, error)
}

它做的事情也很清楚：

从一个 io.Reader 里解析原始内容，并产出标准文档。

这层和 Loader 的边界一定要拆开看：

• Loader 解决'从哪里拿内容'
• Parser 解决'拿到内容后按什么规则解释'

这个区别看着像概念问题，实际上很工程。

因为同样是一份原始数据：

• 当它是 .txt 时，你可能直接按文本处理
• 当它是 .html 时，你通常要提正文、去标签
• 当它是 .pdf 时，你可能要按页或按布局抽取内容

这些差异，不该压在 Loader 里写成一个越来越大的 switch，而应该下沉到 Parser 层。

官方给 Parser 的两个公共 Option 也很有意思：

• WithURI
• WithExtraMeta

这两个能力其实已经把 Parser 的工程定位说透了。

WithURI 说明解析器不只是吃字节流，它还会利用来源信息决定解析行为。
ExtParser 能按扩展名挑解析器，靠的就是这个。

WithExtraMeta 则说明解析不是只管正文，元数据也应该在这一层被合理补齐并合并进文档。

说白了，很多人以为 Loader 是主角、Parser 是配件。
但真到了多格式和生产环境中，你会发现：

Loader 决定的是入口通不通，Parser 决定的是进来的内容是不是'可用的文档'。

5. 一条完整链路在 Eino 里到底怎么走

如果把文档接入链路压成一条直线，它大致是这样：

URI -> Loader 获取原始内容 -> Parser 依据格式解析 -> 构造 []*schema.Document -> 进入 Chain / Graph -> 再进入后续切分、索引、检索链路

这里最关键的一点是：

Loader 的输出不是一个局部变量，而是后续编排系统的正式输入。

所以你才能在 Chain 里直接接它：

chain := compose.NewChain[document.Source, []*schema.Document]()
chain.AppendLoader(loader)

也能在 Graph 里把它当节点挂进去：

graph := compose.NewGraph[document.Source, []*schema.Document]()
graph.AddLoaderNode("loader_node", loader)

这已经说明，官方设计 Loader 时，压根没把它当成一个'顺手写的帮助函数'，它从一开始就是可编排组件。

你如果把这层看明白，再回头看 RAG，就会顺很多。

很多人把知识库理解成'拿一堆文件，切一切，存向量库'。
这当然没错，但真正第一步其实是：

让不同来源的文档，以统一协议、带着必要元数据、可被观察地进入系统。

这一步就是 Loader 和 Parser 共同完成的。

6. 一个最小例子，把 FileLoader、ExtParser 和元数据串起来

如果只讲概念，还是容易飘。
所以可以看一个最小组合：
注意处理错误以便排查。

// 创建纯文本解析器，作为未知扩展名文件的兜底解析器。
textParser := parser.TextParser{}

// 创建 HTML 解析器，仅提取 body 节点内容，避免把 head、script 等无关内容混入文档。
htmlParser, _ := html.NewParser(ctx, &html.Config{
	Selector: gptr.Of("body"),
})

// 创建 PDF 解析器，用于解析 .pdf 文件内容。
pdfParser, _ := pdf.NewPDFParser(ctx, &pdf.Config{})

// 按文件扩展名分发到对应解析器：
// - .html 使用 HTML 解析器
// - .pdf 使用 PDF 解析器
// - 其他类型回退到纯文本解析器
extParser, _ := parser.NewExtParser(ctx, &parser.ExtParserConfig{
	Parsers: map[string]parser.Parser{
		".html": htmlParser,
		".pdf":  pdfParser,
	},
	FallbackParser: textParser,
})

// 创建文件加载器：
// - UseNameAsID=true 表示使用文件名作为文档 ID，便于排查和追踪来源
// - Parser 指定统一的扩展名解析器
loader, _ := file.NewFileLoader(ctx, &file.FileLoaderConfig{
	UseNameAsID: true,
	Parser:      extParser,
})

// 加载并解析目标文件，返回标准化后的文档列表。
docs, _ := loader.Load(ctx, document.Source{
	URI: "./testdata/test.html",
})

// 输出文档 ID（此处通常为文件名或基于文件名生成的标识）。
fmt.Println(docs[0].ID)

// 输出解析后的正文内容。
fmt.Println(docs[0].Content)

// 输出文档元数据，便于调试解析结果和来源信息。
fmt.Printf("%#v\n", docs[0].MetaData)

这段代码里，最该看的不是 API 语法，而是职责分工：

• FileLoader 负责把本地文件变成可读内容
• ExtParser 负责按扩展名把内容交给合适的解析器
• 最终统一产出 schema.Document

也就是说，真正让 .html、.pdf、普通文本走出不同解析路径的，不是 FileLoader，而是 ExtParser 背后的 Parser 选择机制。

这里还有一个很容易被忽视的点：

MetaData 不是在最后'随手补一点信息'，而是从解析阶段就应该被认真传递和保存。

比如来源 URI、扩展名、页面信息，这些字段现在看着不起眼，可一旦你后面要做来源回溯、切分定位、召回解释，它们都会变得非常值钱。

7. Option 和 Callback 为什么不是装饰品

很多人一看到 Option，会下意识把它理解成'几个可选参数'；一看到 Callback，又觉得'加载文档还需要回调吗'。
这么理解不能说错，但都太轻。

先说 Option。

Loader 公共层没有很重的通用 Option，具体实现可以通过 WrapLoaderImplSpecificOptFn 扩展自己的运行时参数。
Parser 这边则分成两层：

• 公共 Option：WithURI、WithExtraMeta
• 实现特定 Option：通过 WrapImplSpecificOptFn 扩展

这意味着 Option 在这里真正扮演的是'运行时扩展入口'，不是参数补丁。

再说 Callback。

Loader 的回调输入输出是官方明确给出来的：

• LoaderCallbackInput
• LoaderCallbackOutput

这件事的意义很直接：

你可以观察文档什么时候开始加载、加载了哪个来源、最后产出了多少个文档、失败发生在哪一步。

一旦链路里同时有本地文件、网页、S3，多种 Parser 并存，没有观测你会很快掉进黑盒。

所以 Callback 的价值，不是'打印两行日志'，而是把文档加载这一步正式接进可观测链路。

8. 自己实现 Loader / Parser 时，真正该守住哪些边界

如果你要自己写一个 Loader，最容易犯的错，就是把'来源获取''内容解析''元数据组装''回调处理'全部揉进一个大函数里。
代码当然也能跑，但只要格式一多、来源一多、链路一长，维护成本就会立刻上来。

更稳的做法，应该像下面这样收：

func (l *CustomLoader) Load(
	ctx context.Context,
	src document.Source,
	opts ...document.LoaderOption,
) ([]*schema.Document, error) {
	// 合并调用方传入的可选参数，并以 Loader 默认超时作为基线配置。
	loaderOpts := document.GetLoaderImplSpecificOptions(&loaderOptions{
		Timeout: l.timeout,
	}, opts...)

	// 打开数据源，返回可读取的流；由当前方法统一负责关闭。
	reader, err := l.open(ctx, src, loaderOpts)
	if err != nil {
		return nil, err
	}
	defer reader.Close()

	// 触发加载开始回调，便于链路追踪、审计和观测。
	ctx = callbacks.OnStart(ctx, &document.LoaderCallbackInput{
		Source: src,
	})

	// 调用底层解析器解析文档内容，并注入标准来源信息：
	// - URI：供解析器识别文件类型或来源
	// - source 元数据：便于后续检索、追踪和排障
	docs, err := l.parser.Parse(ctx, reader, parser.WithURI(src.URI), parser.WithExtraMeta(map[string]any{"source": src.URI}),)
	if err != nil {
		// 解析失败时上报错误回调，确保监控链路完整。
		callbacks.OnError(ctx, err)
		return nil, err
	}

	// 解析成功后触发结束回调，输出源信息和解析结果。
	callbacks.OnEnd(ctx, &document.LoaderCallbackOutput{
		Source: src,
		Docs:   docs,
	})
	return docs, nil
}

这段骨架里，真正该守住的是四条边界：

1. Loader 负责来源接入，不负责格式解释。

打开文件、请求网页、拉取对象存储，这些属于 Loader。
至于 HTML 怎么提正文、PDF 怎么抽文本，这些应该交给 Parser。

2. Parser 负责内容解释，不负责到处拿数据。

它吃的是 io.Reader，不是 URL，也不是文件系统路径。
这样它才可复用，也更容易做单测。

3. URI 和 MetaData 要沿着链路往下传。

如果你自己写 Loader，却忘了把 src.URI 和额外元数据传给 Parser，很多扩展能力就会直接失效。
最典型的就是 ExtParser 选不对解析器，或者解析后的文档丢了来源信息。

4. 回调和错误不要被吞。

加载失败时要返回有意义的错误。
能进回调链路的地方，也别省。
真正到了线上，排障时你会感谢自己没把这一步写成黑盒。

9. 总结

如果把这篇压成一句话，那就是：

Document Loader 解决的是来源收口，Parser 解决的是内容解释；前者让文档能进系统，后者决定进来的到底是不是'可用文档'。

再压缩成三句话，就是：

• Loader 不是简单读取器，而是文档进入 Eino 的统一入口
• Parser 不是配角，它决定原始内容怎样被解释成标准文档
• MetaData、Option、Callback 说明这条链路从一开始就是工程组件，不是一次性 demo 代码

所以别把 Document Loader 只当成'读取 PDF、读取网页'的小功能。
你一旦把这层看懂，后面再去接 Indexer、Retriever，或者继续往更完整的 RAG 流程走，很多设计都会顺理成章。

回顾本文内容定位，在文档进行 RAG 链路前，所讲内容处于以下环节：
原始文档 / 网页 / 文件 → 加载与解析 → 切分 → 向量化 → 建索引 → 检索 → 交给大模型生成答案

参考资料

• CloudWeGo Eino Document Loader 使用说明
• CloudWeGo Eino Document Parser 接口使用说明
• CloudWeGo Eino components/document/interface.go
• CloudWeGo Eino components/document/parser/interface.go