AI 智能体 vs. 原始 LLM API：.NET 中为什么需要文档层

一位用户上传了一份发票 PDF，然后提出需求：

“提取明细行，计算合计，生成一份格式化的 Excel 报表。”

现代 LLM 能够理解这份发票，也能识别你需要的信息。但这只解决了问题的一半。你的应用仍然需要将这种理解转化为一个真实、格式正确的 .xlsx 文件，并具备所需的文档结构。

这就是”理解文档”与”操作文档”之间的鸿沟。 原始 LLM API 提供语言和推理能力，但本身并不提供完整的 Office 文档操作工作流。文档 AI 智能体将 LLM 与确定性文档处理 SDK 连接起来——LLM 决定该做什么，文档层执行文件操作。

快速导航

原始 LLM API 的问题
文档 AI 智能体补充了什么
逐项对比
何时选择哪种方案
C# 最小示例
.NET 团队为何选择 Spire.Agent.Office
常见问题

1. 原始 LLM API 的问题

直接调用 gpt-4 或 claude 来”处理文档”，在生产环境中会面临三个方面的问题。一旦文档工作流超越了简单的文本提取，需要可靠的文件操作、校验和格式化，这些问题就会凸显出来。

1.1 LLM 无法可靠地读写 Office 文件

当模型和 API 支持相关文件或多模态输入时，大语言模型可以理解文档内容，但这并不等于确定性的文档操作。模型或许能分析 PDF 中的文本、表格或视觉内容，但这并不意味着它能通过 LLM API 本身确定性地修改工作簿、保留所有 Office 特有属性，并将结果保存为生产可用的 .xlsx 文件。当 Office 文件被传入原始 LLM API 时，模型接收到的可能是提取或转换后的内容，而非原生的、可编辑的工作簿对象。即使模型能理解工作簿内容，API 本身也不提供保留和修改工作簿原生结构（工作表、命名区域、公式、条件格式、合并单元格、数字格式）的确定性操作。

原始 LLM 文档解析可以提取有用的语义信息，但语义解析与保留和操作原生文档结构是两回事。

写入是同一问题的反向版本。原始 LLM API 本身不提供确定性的 Office 文档操作层。LLM 可以描述报表应包含什么内容，但生成有效的 .docx 或 .xlsx 文件需要额外的工具。要从原始 LLM 生成真正的 Office 输出，你必须搭建一条重建管线：解析模型的文本响应、将字段映射到单元格或段落、应用格式、自行写入文件。这条管线并不简单——而且正是它在生产环境中出问题的地方。

1.2 格式无法保证

文档工作流承载着重要的格式信息：发票报表中的列标题、财务表格中的数字格式、标记差异的条件填充、管理报表中的表格样式。原始 LLM API 返回的是模型生成的内容（如文本、JSON 或工具调用），本身并不提供格式化的 Office 文档作为输出。当模型的响应需要被重建为 Office 文件时，格式很难保留——一张没有数字格式的 Excel 表，需要有人手动修正后才能交给财务部门。

即使 LLM 产生了结构化输出（JSON、Markdown 表格），结构化输出也不等于结构化文档输出。JSON 给你的是结构化数据，而非结构化的 Office 文档。JSON 响应可以描述单元格、段落、表格或格式指令，但仍需要额外的文档处理层将这些指令应用到真实的 .xlsx、.docx、.pptx 或 .pdf 文件上。于是你不得不维护一个格式化器、一个字段映射器和一个样式应用器——LLM 对这些统统帮不上忙。

1.3 你在重新实现整个编排逻辑

原始 LLM 文档管线不是一次 API 调用，而是一整条技术栈：

提示词设计——模板化提示词，文档布局一变就可能失效
提取——可能需要额外的文档处理工具，从 PDF、Word 和 Excel 文件中提取结构化内容后才能交给 LLM
解析——JSON 解析逻辑，将 LLM 响应转为结构化数据
重试逻辑——处理幻觉输出、速率限制和内容审查拦截
文件 I/O——读取输入、写入输出、管理临时文件
输出校验——在返回给用户之前，检查生成的文件是否有效且格式正确

到这一步，你实际上在构建一套文档处理方案——LLM 只是其中一个组件，而非方案本身。每增加一种文档类型、一次结构变更或一种输出格式，都需要重新调提示词、重新测试模型特有的行为。维护成本随你支持的文档类型数量线性增长。

2. 文档 AI 智能体补充了什么

文档 AI 智能体通过将 LLM 与确定性文档处理层配对，解决了上述三个问题。分工很清晰：

LLM 负责理解。 它读取自然语言指令，决定提取或生成什么内容，并确定输出的结构。
文档层负责执行。 它读写真实的 Office 和 PDF 文件，保留格式，应用样式，通过确定性文档操作生成结构有效的文件。

智能体不是让 LLM 去”猜”文档结构，而是调用确定性的文档操作。模型不需要自行构造 Office 文件格式——它产生意图，文档层执行对应的文件操作。

两种架构并排对比：

原始 LLM API 管线与文档 AI 智能体架构对比

实际效果

原始 LLM 的问题	智能体的解决方式
无法原生操作 `.xlsx`	文档层原生读取和操作工作簿
无法确定性地生成 Office 文件	文档层直接创建输出文件
重建过程中格式可能丢失	文档层处理样式和数字格式
模型生成的结构可能不一致	文档操作是确定性的
你需要自己搭建周边管线	Agent SDK 提供文档处理工作流

核心洞察：LLM 是大脑，文档层是双手。 原始 LLM API 给了你大脑，然后期望你自己造出双手。文档 AI 智能体两者都给你，而且集成在一起，一次 SDK 调用完成。

单独的文档 SDK 可以操作文件，但它不理解自然语言意图。AI 智能体将确定性文档层与 LLM 结合，用户只需描述期望的工作流，而不必手动实现每一个文档操作。价值不在于”文档 SDK + AI”的简单叠加，而在于整条管线：自然语言指令 → LLM 推理 → 确定性文档操作。

想进一步了解文档 AI 智能体是怎么构成的、它在内容流水线里处在什么位置，可以看这篇 AI 智能体如何做文档处理：是什么、怎么工作。

3. 逐项对比

维度	原始 LLM API	文档 AI 智能体
文件理解	取决于模型/API 和文件类型	文档层提供原生文档访问
文件操作	需要工具或额外的文档库	内置于文档处理层
格式保真	取决于重建逻辑	由确定性文档 API 处理
输出处理	LLM 响应需解析并转为文件	文档层执行确定性文件创建
代码量	更多应用侧编排代码	自然语言指令 + SDK 配置
维护成本	提示词、解析器、映射和文件逻辑	更多工作流行为可通过指令表达
多格式处理	需要逐格式支持	统一的文档处理工作流
语义准确性	取决于模型和提示词	同样取决于模型和指令
文件校验	应用自行负责	SDK 报告处理成功/失败
.NET 集成	.NET SDK 或 HTTP 集成，另需文档库	原生 C# SDK，内置文档处理
适用场景	以文本为核心的 AI 任务	AI 驱动的文档工作流

4. 何时选择哪种方案

对比的结论不是”智能体永远更好”。原始 LLM API 和文档 AI 智能体服务于不同意图，选择正确的工具取决于工作流的产出物。

适合使用原始 LLM API 的场景

输出是文本，不是文件。 摘要、问答、分类和起草都是文本进、文本出的任务，不需要文档层。
你已有 LLM 技术栈。 如果团队已投入提示词工程、RAG 和编排基础设施建设，对于纯文本工作流，增加文档 SDK 可能没有必要。
输入是纯文本或 Markdown。 如果源材料本身就是文本——而非 .pdf 或 .xlsx——提取问题消失，原始 LLM 调用就是最简单的路径。

适合使用文档 AI 智能体的场景

输出必须是真实的 Office 或 PDF 文件。 如果交付物是给财务的 .xlsx 工作簿、给管理层的 .docx 报告或用于分发的 .pdf，当工作流必须可靠地生成有效、格式正确的 Office 文件时，文档处理层就变得重要。
输入跨多种格式。 PDF、Word 文档、Excel 文件和扫描图像在同一工作流中到达。原始 LLM 需要为每种格式配备单独的提取库；智能体用一条指令全部处理。
格式很重要。 列标题、数字格式、条件填充、表格样式、字体——如果业务团队在意文件的外观，文档层就是保留它的关键。
你在 .NET 环境中。 原生 C# SDK 将 AI 编排与文档处理合为一体，相比 LLM SDK 外接多个文档库，可以减少应用侧的集成代码。
工作流经常变化。 新供应商、新报表布局、新校验规则——当瓶颈在于每次变更都要改代码时，编辑一条指令比改代码更快、更省。

决策摘要

问题	原始 LLM API	文档 AI 智能体
输出是真实文件（Excel、Word、PDF）？	需要额外工具	是
格式需要保留？	取决于你的重建管线	由文档层处理
输入是多种 Office 格式？	需要逐格式提取	是
这是纯文本任务（摘要、问答）？	是	可以，但没必要
需要在 .NET 中原生操作文档？	需要额外的文档库	内置于工作流
工作流规则会频繁变化？	提示词和解析器需重新调优	编辑指令即可改变行为

5. C# 最小示例

差异在代码中最清晰可见。下面是同一个任务——从 PDF 发票中提取数据并生成格式化的 Excel 报表——用两种方式实现。

原始 LLM API 方式

// 简化的原始 LLM 管线——示意性架构，非生产代码。

// 1. 使用文档处理工具获取文档内容
//    （本示例使用提取的文本来演示一种常见的原始 LLM 架构；
//    部分现代 LLM API 也可以直接接受 PDF。）
string documentText = ExtractTextFromPdf(@"C:\invoices\supplier-a.pdf");

// 2. 将提取的内容发送给 LLM
string json = await CallLlmAsync(
    "以 JSON 格式提取供应商、发票日期、明细行和合计。",
    documentText);

// 3. 反序列化并校验模型响应
InvoiceData data = JsonSerializer.Deserialize<InvoiceData>(json)
    ?? throw new InvalidOperationException("LLM 响应无效。");

// 4. 使用文档库创建 Excel 文件
using var workbook = new Workbook();
var sheet = workbook.AddWorksheet("Invoice");

// ... 将数据映射到单元格并应用格式
workbook.SaveToFile(@"C:\output\report.xlsx");

示意管线： API 和文档库调用已简化，重点在于架构而非特定供应商 SDK。

文档 AI 智能体方式

// 文档 AI 智能体：一条指令，真实文件输出
using Spire.Agent.Office.AI;
using Spire.Agent.Office.Extensions;
using Spire.Xls;

string? spireToken = Environment.GetEnvironmentVariable("SPIRE_TOKEN");
if (string.IsNullOrEmpty(spireToken))
    throw new InvalidOperationException("SPIRE_TOKEN 未设置。");

AIOptions agentOptions = new AIOptions();
agentOptions.WorkDir = @"C:\output";
agentOptions.SpireToken = spireToken;

string instruction =
    "读取附件中的发票 PDF，提取供应商名称、发票日期、" +
    "明细行（描述、数量、单价、金额）和合计。" +
    "创建一个工作簿，包含格式化的标题行、金额列的数字格式、" +
    "以及汇总行。保存为 .xlsx 文件。";

string[] attachments = { @"C:\invoices\supplier-a.pdf" };

using (Workbook wb = new Workbook())
{
    AIResult result = wb.AI(agentOptions).ExecuteInstruction(
        wb,
        instruction,
        @"C:\output\report.xlsx",
        attachments);

    if (result == null || !result.Success)
        throw new InvalidOperationException(
            $"处理失败：{result?.ErrorMessage}");
}

智能体读取 PDF 发票并生成格式化的 Excel 报表：

PDF 发票输入与格式化 Excel 报表输出

关键 API 调用

Workbook.AI(agentOptions)——将 AI 文档处理器附加到工作簿对象
ExecuteInstruction(doc, instruction, savePath, attachments)——执行指令并写入输出文件
AIResult.Success / AIResult.ErrorMessage——校验结果并暴露错误

原始 LLM 方式是四个独立问题（提取、提示、解析、文件写入）拼接在一起。智能体方式是一条指令加一次结果检查。两种方式最终都能生成 .xlsx 文件，但原始 LLM 方式需要你自行构建和维护文档生成层。智能体将文档处理层集成到工作流中，LLM 专注于解读指令，SDK 负责文档操作。

想看完整工作流？这篇在 .NET 中用 AI 智能体自动化发票处理展示了从提取、校验到出报告的全流程。

6. .NET 团队为何选择 Spire.Agent.Office

上面的对比刻意保持产品中立——同样的架构（LLM + 文档层）适用于任何有能力的模型和任何文档 SDK。Spire.Agent.Office 对 .NET 团队的价值体现在三个具体方面：

原生多格式处理。 PDF、Word 文档、Excel 文件和基于图像的文档工作流都可以纳入智能体工作流。智能体在一条指令中跨格式读取、提取和生成——不需要逐格式提取库，不需要逐格式输出格式化器。
通过确定性文档操作保留格式。 文档层保持列标题、数字格式、条件填充、表格样式和字体不变。从现有模板工作时，明确指示智能体保留原始布局和样式，输出就能忠于模板，无需额外代码。
原生 .NET 集成。 它是一个 C# SDK，直接放入现有 .NET 应用。不需要构建或维护独立的文档处理服务，不需要跨服务管道，不需要 HTTP 编排层。上面的示例涵盖了核心集成面：SDK 配置、一条指令、一次结果检查。

如果你已经在使用 Spire.Office 做文档处理，智能体就是自然的下一层：同一个 Workbook 对象获得了一个 AI() 处理器，将指令转化为已执行的工作流。你已熟悉的确定性 SDK 成为了智能体调用的文档层。

7. 常见问题

我不能直接把 PDF 发给 LLM API 吗？

可以。现代 LLM API 能直接接受部分文档类型，包括 PDF。关键区别在于：文件输入让模型可以访问文档内容，但不会自动给你的应用提供确定性 API 来修改原始 Office 结构并保存生产可用的输出文件。例如，模型可能正确识别了 PDF 中的发票表格，但将这种理解转化为格式化的 .xlsx 仍然需要文档生成逻辑。

“文档层”到底是什么？

文档层是一个确定性 SDK，读写 Office 和 PDF 文件并操作其原生文档结构。它处理 LLM 无法完成的操作：打开 .xlsx 并保留其工作表和公式、写入 .docx 并应用正确的样式和标题、合并单元格、应用条件格式、通过确定性文档 API 创建结构有效的 Office/PDF 输出。在 Spire.Agent.Office 中，文档层就是 Spire.Office SDK——LLM 决定做什么，文档层去做。

这不就是 RAG 多了几步吗？

不是。RAG（检索增强生成）主要关注检索相关信息来为模型响应提供依据。文档 AI 智能体增加了另一项职责：执行文档操作并生成或修改真实文件。文档智能体读写真实文件，保留格式，生成的是有效的 Office 文档作为结构化输出，而非文本响应。

Spire.Agent.Office 支持哪些 AI 模型？

Spire.Agent.Office 通过 SpireToken 密钥连接大语言模型，支持托管模型 API 和自定义模型端点。如需了解你的部署中支持哪些提供商和模型协议，请联系销售。

我的数据会留在自己的环境中吗？

SDK、模板和文档处理在你的应用内运行——文件不会上传到第三方文档服务进行存储或转换。要分析内容，AI 需要相关文本，这些文本会发送给模型进行处理。如果模型端点部署在你自己的网络内，且你的配置不将文档内容发送到外部，那么文档内容可以留在你的基础设施内。如果你通过托管模型 API（如 OpenAI 或 Azure OpenAI）连接，相关内容将按照你的配置传输给该提供商。