1. 项目概述为什么我们需要“结构化输出”如果你最近在折腾大语言模型应用尤其是基于RAG检索增强生成的项目那你大概率听说过LlamaIndex。它确实是个好工具能帮你轻松地把文档喂给模型然后进行问答。但不知道你有没有遇到过这样的场景你问模型“请总结一下这份财报里第三季度的营收和利润”结果它给你回了一大段散文式的描述虽然信息都对但你想把它自动填入数据库或者生成一个JSON接口返回给前端时就傻眼了——你得写一堆复杂的正则表达式或者后处理逻辑去“猜”和“抠”数据。这个过程费时费力还容易出错。这就是“非结构化输出”的典型痛点。“玩转LlamaIndex结构化输出”要解决的正是这个问题。它不是一个简单的功能开关而是一套将大语言模型“信马由缰”的文本生成能力驯化成严格遵循预定格式如JSON、Pydantic模型、甚至SQL语句的“标准答案”的工程方法。这背后的核心价值在于机器可读性和自动化。当模型的输出是结构化的你的下游系统——无论是数据分析流水线、自动化报告工具还是API服务——就能像处理普通程序数据一样无缝、可靠地消费这些结果极大提升了AI应用的集成度和实用性。简单来说结构化输出让AI从“会说话的鹦鹉”变成了“会填表的助理”。对于开发者而言这意味着更少的胶水代码、更高的系统可靠性以及将LLM能力真正产品化的关键一步。无论你是想从海量文档中自动提取实体信息、生成标准化的报告摘要还是构建一个能返回复杂嵌套数据的智能问答API掌握LlamaIndex的结构化输出能力都是必经之路。2. 核心思路与方案选型不止一种“结构法”在LlamaIndex中实现结构化输出并非只有一条路。根据你的具体场景、对输出格式的严格程度要求以及开发便利性主要有几种主流方案。理解它们各自的原理和适用场景是做出正确技术选型的第一步。2.1 方案一基于Pydantic模型的“强类型”输出这是目前最推荐、也是功能最强大的方式。其核心思想是用代码定义结构让模型来填充。你首先需要定义一个Pydantic数据模型一个Python类这个类精确描述了你希望输出数据的形状包括字段名、类型str, int, float, bool, List, 嵌套模型等甚至可以加上字段描述和示例。from pydantic import BaseModel, Field from typing import List class QuarterlyFinancials(BaseModel): 季度财务数据 quarter: str Field(description财政季度例如 Q3 2023) revenue: float Field(description营收单位百万美元) profit: float Field(description净利润单位百万美元) growth_rate: float Field(description同比增长率百分比) key_highlights: List[str] Field(description本季度关键业务亮点)然后你通过LlamaIndex的PydanticProgram或相关查询引擎将这个模型“喂”给LLM。模型在生成回答时会努力使其输出符合这个模型的约束并最终返回一个该模型的实例对象。这种方式的好处是“双保险”第一LLM在生成时会受到明确的格式引导第二即使LLM的输出有轻微偏差Pydantic在实例化时还会进行类型验证和转换确保最终得到的数据是干净、类型正确的Python对象。注意不是所有模型都原生支持严格的Pydantic输出。像GPT-4、Claude 3等高级模型对此支持得很好。对于一些开源模型可能需要依赖其微调能力或通过Prompt工程进行强引导。2.2 方案二基于JSON Schema的“通用契约”输出如果你的应用栈不是纯Python或者你需要一个更语言中立的契约JSON Schema是一个绝佳选择。其思路与Pydantic类似但使用的是JSON Schema标准来定义结构。LlamaIndex允许你提供一个JSON Schema然后要求模型输出符合该Schema的JSON字符串。{ $schema: http://json-schema.org/draft-07/schema#, type: object, properties: { quarter: { type: string, description: 财政季度 }, revenue: { type: number, description: 营收 } }, required: [quarter, revenue] }这种方式非常适合前后端分离的架构。后端Python用LlamaIndex生成符合Schema的JSON前端JavaScript/TypeScript可以直接用同样的Schema来验证和消费数据实现了全栈类型安全。2.3 方案三基于文本模板与后处理的“引导式”输出这是比较传统和灵活的方法。你并不强制模型输出某种序列化格式而是通过精心设计的Prompt模板引导模型以高度规律化的文本格式输出。例如请按以下格式总结财务数据 季度[季度名称] 营收[数字] 百万美元 利润[数字] 百万美元 亮点 - [亮点1] - [亮点2]然后你再编写一个简单的解析器可能是几行正则表达式或者按行按分隔符拆分来提取这些信息。这种方法的优势是兼容性极广几乎适用于任何LLM且对Prompt工程的要求更直观。缺点是脆弱如果模型没有严格遵守格式比如多了一个空行或者用了不同的标点你的解析器就可能失败需要加入更多的容错逻辑。方案选型心得 对于全新的、追求稳健和生产级的项目优先选择Pydantic模型方案。它提供了最好的开发体验和运行时安全性。如果你的数据契约需要跨多种编程语言共享JSON Schema方案是桥梁。而如果你只是在做快速原型验证或者对接的模型能力非常有限那么从文本模板引导开始会更快捷但务必预留出后期向更强类型方案迁移的余地。3. 核心细节解析与实操要点选定了方案接下来就是深入细节。以最强的Pydantic方案为例在实际操作中有几个关键点直接决定了成功率和输出质量。3.1 Prompt工程的隐形力量很多人以为定义了Pydantic模型就万事大吉其实不然。模型如何理解你的意图很大程度上取决于包裹在查询之外的“系统提示词”和“用户提示词”。LlamaIndex在调用PydanticProgram时会自动将你的模型结构转换成对模型的一段描述但这可能不够。你需要主动优化Prompt在查询时除了基础问题最好在指令中再次明确你的要求。例如在调用查询引擎的query方法时可以这样response query_engine.query( “”” 请从提供的上下文中提取关于2023年第三季度的财务信息。 请确保严格按照指定的JSON格式即之前定义的QuarterlyFinancials模型返回数据。 如果某个字段在上下文中找不到明确信息请将其设置为null或合理的默认值但不要虚构数据。 “”” )这段指令做了三件事1) 明确了任务提取信息2) 强调了格式要求3) 给出了处理缺失值的策略。这能显著提高模型输出与模型结构对齐的几率。3.2 上下文与检索策略的匹配结构化输出不是空中楼阁它严重依赖于检索到的上下文质量。如果你的问题是“提取某公司的营收”但检索器返回的5个文档片段里4个在讲公司历史1个模糊提到了“收入增长”那模型再厉害也巧妇难为无米之炊。关键点在于让检索为提取服务你需要调整检索策略使其更倾向于返回包含目标数据结构信息的文本。例如优化检索查询不要直接用原始问题“总结Q3财报”去检索。可以将其重写为“Q3 revenue profit financial highlights numbers”这些关键词更可能命中包含数据的句子。使用摘要索引对于需要整体理解的文档如一份完整的财报可以考虑使用SummaryIndex让模型先看到文档的全局摘要再进行提取这有助于理解数据的上下文关系。调整分块大小和重叠对于表格数据或密集数据段落适当增大文本分块chunk的大小并设置重叠overlap可以避免关键数据被割裂在不同的块中。3.3 处理模型的“不听话”与边界情况即使做了上述工作模型偶尔还是会输出不符合要求的格式。这时需要一套应对策略。重试与降级最简单的策略是设置自动重试。当Pydantic解析失败时捕获验证异常将模型的原始输出和错误信息一起作为一个新的、更强调格式的提示词再次发送给模型。通常一两次重试就能解决问题。如果多次重试失败可以考虑降级到“引导式文本输出解析”的方案作为保底。提供示例在定义Pydantic模型时利用Field的examples参数提供一两个清晰的示例这对模型理解格式有奇效。温度参数将模型的温度temperature调低例如0.1或0可以减少输出的随机性使其更倾向于遵循指令格式。但这可能会牺牲一些创造性在提取任务中通常不需要创造性。4. 实操过程构建一个财报信息提取引擎让我们通过一个完整的例子将上述理论付诸实践。目标是构建一个能从上市公司财报PDF中自动提取指定季度关键财务数据并返回JSON的引擎。4.1 环境准备与依赖安装首先确保你的环境已就绪。除了LlamaIndex我们还需要文档加载器和解析器。# 核心依赖 pip install llama-index llama-index-llms-openai llama-index-readers-file pymupdf # 用于处理PDF也可以使用 llama-index-readers-pdf # 本例使用 pymupdf (fitz) 作为PDF后端速度较快这里选择llama-index-llms-openai因为我们使用GPT-4作为LLM引擎它在结构化输出上表现最稳定。如果你使用其他模型如Anthropic Claude或本地部署的Llama 3需要安装对应的集成包。4.2 文档加载与索引构建假设我们有一个名为q3_earnings_report.pdf的财报文件。from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.core.node_parser import SentenceSplitter from llama_index.core import Settings from llama_index.llms.openai import OpenAI import os # 1. 设置LLM os.environ[“OPENAI_API_KEY”] “your-api-key” Settings.llm OpenAI(model“gpt-4-turbo-preview”, temperature0.1) # 低温度保证稳定性 # 2. 加载文档 documents SimpleDirectoryReader(input_files[“./q3_earnings_report.pdf”]).load_data() # 3. 自定义文本分块策略 # 财报数据密集句子可能较长我们适当增大块大小并设置重叠以避免数据割裂 text_splitter SentenceSplitter(chunk_size1024, chunk_overlap200) nodes text_splitter.get_nodes_from_documents(documents) # 4. 构建向量索引 # 使用默认的OpenAI嵌入模型即可 index VectorStoreIndex(nodes)这里的关键在于chunk_size和chunk_overlap的设置。对于财报这种包含表格和连续数据的文档1024的块大小和200的重叠是一个不错的起点可以有效防止“营收”和对应的“数字”被分到两个不同的块里。4.3 定义Pydantic模型与查询引擎现在定义我们想要提取的数据结构并创建专门的查询引擎。from llama_index.core import PromptTemplate from llama_index.core.program import MultiModalLLMCompletionProgram from pydantic import BaseModel, Field from typing import List, Optional # 1. 定义精细化的数据模型 class FinancialMetric(BaseModel): name: str Field(description财务指标名称如 Total Revenue) value: float Field(description指标数值) unit: str Field(description单位如 million USD, %) change: Optional[float] Field(None, description同比或环比变化百分比) class QuarterlyReport(BaseModel): company: str Field(description公司名称) fiscal_quarter: str Field(description财政季度如 Q3 2024) reporting_period: str Field(description报告期如 Ended Sep 30, 2024) metrics: List[FinancialMetric] Field(description本季度关键财务指标列表) management_comment: Optional[str] Field(None, description管理层关于本季度业绩的简要评述) # 2. 创建Pydantic查询程序 from llama_index.core.program import LLMTextCompletionProgram program LLMTextCompletionProgram.from_defaults( output_clsQuarterlyReport, prompt_template_str“”” 你是一个专业的财务分析师。请从以下上下文信息中提取关于{company_name}公司{target_quarter}的财务报告数据。 上下文信息 {context_str} 请严格按照提供的QuarterlyReport Pydantic模型格式填充数据。 注意 1. 只提取上下文中明确提及的数据不要推断或计算。 2. 对于metrics字段请尽可能多地提取不同的财务指标如营收、净利润、毛利率、每股收益等。 3. 如果上下文中没有管理层评述management_comment字段可以留空。 “””, verboseTrue, ) # 3. 组装检索与查询流程 from llama_index.core import QueryBundle query_engine index.as_query_engine(similarity_top_k5) # 检索前5个相关片段 def extract_structured_data(company_name: str, target_quarter: str) - QuarterlyReport: # 步骤1检索相关上下文 query_str f“{company_name} {target_quarter} revenue profit earnings financial statements” retrieved_nodes query_engine.retrieve(QueryBundle(query_str)) context_str “\n\n”.join([n.node.get_content() for n in retrieved_nodes]) # 步骤2调用Pydantic程序进行结构化提取 result program( company_namecompany_name, target_quartertarget_quarter, context_strcontext_str ) return result # 4. 执行查询 try: report extract_structured_data(“Apple Inc.”, “Q3 2024”) print(report.json(indent2)) except Exception as e: print(f“提取失败: {e}”) # 这里可以加入重试逻辑或降级处理这段代码是核心。我们创建了一个LLMTextCompletionProgram它内部会处理如何将我们的Pydantic模型、Prompt模板和上下文结合起来发送给LLM并解析返回结果。prompt_template_str中的{context_str}、{company_name}等是占位符会在运行时被替换。4.4 结果后处理与验证程序返回的report已经是一个QuarterlyReport类的实例。你可以直接访问其属性也可以轻松地将其转换为字典或JSON。# 访问数据 print(f“公司: {report.company}”) print(f“季度: {report.fiscal_quarter}”) for metric in report.metrics: print(f“ - {metric.name}: {metric.value} {metric.unit}”) # 转换为JSON便于API返回或存储 import json json_output report.json() data_dict report.dict()为了确保数据质量你可以在FinancialMetric模型中添加更严格的验证规则例如使用Field(ge0)来确保营收不为负数或者在业务逻辑层对提取到的指标进行合理性检查例如净利润通常不会大于营收。5. 常见问题与排查技巧实录在实际操作中你一定会遇到各种问题。下面是我踩过坑后总结的一些典型问题及其解决方法。5.1 问题模型返回了文本但无法解析成Pydantic对象抛出验证错误。排查思路查看原始输出将verboseTrue设置为program的参数或者捕获异常后打印出LLM返回的原始文本。很多时候模型确实在努力遵循格式但在JSON字符串里多了个尾随逗号或者键名用了中文引号。检查Prompt你的Prompt是否足够清晰地强调了“必须输出JSON”对于复杂嵌套结构在Prompt中提供一个简明的示例One-shot learning效果极佳。简化模型如果模型一直无法理解复杂嵌套先尝试定义一个极其简单的、只有两三个扁平字段的模型看是否能成功。如果能再逐步增加复杂度以此定位是模型能力问题还是Prompt描述问题。切换模型如果用的是gpt-3.5-turbo尝试换成gpt-4或gpt-4-turbo。在结构化输出任务上GPT-4系列的表现通常远好于3.5。5.2 问题检索到的上下文不包含我需要的数据导致提取结果为空或不准确。排查思路检查检索结果在调用program之前先打印出context_str。看看检索器到底返回了什么。很可能你的问题“提取净利润”和文档中使用的术语“归母净利润”或“Net Income”不匹配。优化查询词不要用自然语言问题直接检索。像前面提到的将“苹果公司Q3营收多少”重写为“Apple Q3 2024 revenue total income financial statement”。可以尝试多个查询词变体然后合并检索结果。调整检索参数增加similarity_top_k例如从3调到10让更多相关片段进入候选池。也可以尝试不同的检索器比如BM25Retriever关键词匹配与向量检索结合进行混合检索。预处理文档如果PDF解析后格式混乱很多PDF如此数据散落在各处。考虑使用专门的PDF表格提取库如camelot、tabula先提取表格数据将其转换为Markdown或结构化文本再喂给LlamaIndex。这相当于提前做了一次信息结构化。5.3 问题处理速度慢尤其是处理长文档或多个文档时。优化技巧并行处理如果你需要从多个文档中提取相同结构的信息可以为每个文档启动独立的异步任务。LlamaIndex的查询引擎本身是同步的但你可以用asyncio和run_in_executor将其包装。缓存索引构建向量索引是耗时操作。一旦构建好一定要将其持久化到磁盘如使用index.storage_context.persist(persist_dir“./storage”)下次直接加载避免重复计算嵌入向量。精简上下文不是所有检索到的片段都同等重要。在将context_str传递给LLM前可以做一个简单的过滤或摘要。例如只选择与数字、百分比、货币符号高度相关的句子。使用更快的模型/嵌入如果对精度要求不是极致可以尝试gpt-3.5-turbo-instruct模型它在简单提取任务上速度更快。对于嵌入模型可以换用本地轻量级模型如BAAI/bge-small-en能极大加快索引构建和检索速度。5.4 问题输出结构对了但数值或事实有误幻觉。应对策略 这是RAG系统的核心挑战之一。结构化输出解决了格式问题但无法根治幻觉。增强检索质量这是根本。确保检索到的上下文足够相关和准确。可以尝试重新分块、优化嵌入模型、使用重排序技术。在Prompt中加强限制明确写上“只使用提供上下文中的信息不要使用外部知识”和“如果上下文没有明确提及就将对应字段设为null”。置信度评分与人工审核对于关键业务数据如财务数据可以设计一个简单的置信度评分机制。例如检查提取的数值是否在上下文中以完全相同的形式出现。对于低置信度的结果流转到人工审核环节而不是直接进入下游系统。后处理校验编写规则校验数据。例如检查同一份报告中营收是否大于成本季度数据是否在合理范围内等。6. 进阶与LangGraph结合构建结构化输出工作流最新的网络热词提到了llamaindex langgraph这指向了一个更强大的模式使用LangGraph来编排包含结构化输出的复杂、多步骤工作流。LangGraph允许你以图的形式定义AI智能体的执行流程其中每个节点可以是一个工具调用、一个条件判断或者一次LLM调用。想象这样一个场景你需要从一份混合了文本、表格和图表的年报中提取财务数据、总结业务风险、并生成一份投资建议摘要。单一Prompt很难做好所有事。这时可以用LangGraph节点A路由根据用户问题判断任务类型是数据提取、总结还是分析。节点B数据提取调用我们上面构建的PydanticProgram专门提取结构化的财务指标。节点C风险总结调用另一个LLM专门从“风险管理”章节提取关键风险点并以列表形式输出。节点D综合分析将节点B和C的结构化输出作为输入再调用LLM生成最终的投资建议摘要。在这个工作流中结构化输出节点B和C的结果成为了节点之间可靠传递的数据“管道”确保了整个复杂流程的稳定性和可维护性。LlamaIndex与LangGraph的集成使得定义这样的节点和边变得非常直观将一次性的大模型调用拆解成了可调试、可复用、可监控的标准化组件。这是将结构化输出能力从单点工具升级为系统工程的关键一步。 
长河君 · 2026/8/15 3:24:25 · 阅读 1.2k LlamaIndex结构化输出实战：从RAG到JSON的工程化实现
1. 项目概述为什么我们需要“结构化输出”如果你最近在折腾大语言模型应用尤其是基于RAG检索增强生成的项目那你大概率听说过LlamaIndex。它确实是个好工具能帮你轻松地把文档喂给模型然后进行问答。但不知道你有没有遇到过这样的场景你问模型“请总结一下这份财报里第三季度的营收和利润”结果它给你回了一大段散文式的描述虽然信息都对但你想把它自动填入数据库或者生成一个JSON接口返回给前端时就傻眼了——你得写一堆复杂的正则表达式或者后处理逻辑去“猜”和“抠”数据。这个过程费时费力还容易出错。这就是“非结构化输出”的典型痛点。“玩转LlamaIndex结构化输出”要解决的正是这个问题。它不是一个简单的功能开关而是一套将大语言模型“信马由缰”的文本生成能力驯化成严格遵循预定格式如JSON、Pydantic模型、甚至SQL语句的“标准答案”的工程方法。这背后的核心价值在于机器可读性和自动化。当模型的输出是结构化的你的下游系统——无论是数据分析流水线、自动化报告工具还是API服务——就能像处理普通程序数据一样无缝、可靠地消费这些结果极大提升了AI应用的集成度和实用性。简单来说结构化输出让AI从“会说话的鹦鹉”变成了“会填表的助理”。对于开发者而言这意味着更少的胶水代码、更高的系统可靠性以及将LLM能力真正产品化的关键一步。无论你是想从海量文档中自动提取实体信息、生成标准化的报告摘要还是构建一个能返回复杂嵌套数据的智能问答API掌握LlamaIndex的结构化输出能力都是必经之路。2. 核心思路与方案选型不止一种“结构法”在LlamaIndex中实现结构化输出并非只有一条路。根据你的具体场景、对输出格式的严格程度要求以及开发便利性主要有几种主流方案。理解它们各自的原理和适用场景是做出正确技术选型的第一步。2.1 方案一基于Pydantic模型的“强类型”输出这是目前最推荐、也是功能最强大的方式。其核心思想是用代码定义结构让模型来填充。你首先需要定义一个Pydantic数据模型一个Python类这个类精确描述了你希望输出数据的形状包括字段名、类型str, int, float, bool, List, 嵌套模型等甚至可以加上字段描述和示例。from pydantic import BaseModel, Field from typing import List class QuarterlyFinancials(BaseModel): 季度财务数据 quarter: str Field(description财政季度例如 Q3 2023) revenue: float Field(description营收单位百万美元) profit: float Field(description净利润单位百万美元) growth_rate: float Field(description同比增长率百分比) key_highlights: List[str] Field(description本季度关键业务亮点)然后你通过LlamaIndex的PydanticProgram或相关查询引擎将这个模型“喂”给LLM。模型在生成回答时会努力使其输出符合这个模型的约束并最终返回一个该模型的实例对象。这种方式的好处是“双保险”第一LLM在生成时会受到明确的格式引导第二即使LLM的输出有轻微偏差Pydantic在实例化时还会进行类型验证和转换确保最终得到的数据是干净、类型正确的Python对象。注意不是所有模型都原生支持严格的Pydantic输出。像GPT-4、Claude 3等高级模型对此支持得很好。对于一些开源模型可能需要依赖其微调能力或通过Prompt工程进行强引导。2.2 方案二基于JSON Schema的“通用契约”输出如果你的应用栈不是纯Python或者你需要一个更语言中立的契约JSON Schema是一个绝佳选择。其思路与Pydantic类似但使用的是JSON Schema标准来定义结构。LlamaIndex允许你提供一个JSON Schema然后要求模型输出符合该Schema的JSON字符串。{ $schema: http://json-schema.org/draft-07/schema#, type: object, properties: { quarter: { type: string, description: 财政季度 }, revenue: { type: number, description: 营收 } }, required: [quarter, revenue] }这种方式非常适合前后端分离的架构。后端Python用LlamaIndex生成符合Schema的JSON前端JavaScript/TypeScript可以直接用同样的Schema来验证和消费数据实现了全栈类型安全。2.3 方案三基于文本模板与后处理的“引导式”输出这是比较传统和灵活的方法。你并不强制模型输出某种序列化格式而是通过精心设计的Prompt模板引导模型以高度规律化的文本格式输出。例如请按以下格式总结财务数据 季度[季度名称] 营收[数字] 百万美元 利润[数字] 百万美元 亮点 - [亮点1] - [亮点2]然后你再编写一个简单的解析器可能是几行正则表达式或者按行按分隔符拆分来提取这些信息。这种方法的优势是兼容性极广几乎适用于任何LLM且对Prompt工程的要求更直观。缺点是脆弱如果模型没有严格遵守格式比如多了一个空行或者用了不同的标点你的解析器就可能失败需要加入更多的容错逻辑。方案选型心得 对于全新的、追求稳健和生产级的项目优先选择Pydantic模型方案。它提供了最好的开发体验和运行时安全性。如果你的数据契约需要跨多种编程语言共享JSON Schema方案是桥梁。而如果你只是在做快速原型验证或者对接的模型能力非常有限那么从文本模板引导开始会更快捷但务必预留出后期向更强类型方案迁移的余地。3. 核心细节解析与实操要点选定了方案接下来就是深入细节。以最强的Pydantic方案为例在实际操作中有几个关键点直接决定了成功率和输出质量。3.1 Prompt工程的隐形力量很多人以为定义了Pydantic模型就万事大吉其实不然。模型如何理解你的意图很大程度上取决于包裹在查询之外的“系统提示词”和“用户提示词”。LlamaIndex在调用PydanticProgram时会自动将你的模型结构转换成对模型的一段描述但这可能不够。你需要主动优化Prompt在查询时除了基础问题最好在指令中再次明确你的要求。例如在调用查询引擎的query方法时可以这样response query_engine.query( “”” 请从提供的上下文中提取关于2023年第三季度的财务信息。 请确保严格按照指定的JSON格式即之前定义的QuarterlyFinancials模型返回数据。 如果某个字段在上下文中找不到明确信息请将其设置为null或合理的默认值但不要虚构数据。 “”” )这段指令做了三件事1) 明确了任务提取信息2) 强调了格式要求3) 给出了处理缺失值的策略。这能显著提高模型输出与模型结构对齐的几率。3.2 上下文与检索策略的匹配结构化输出不是空中楼阁它严重依赖于检索到的上下文质量。如果你的问题是“提取某公司的营收”但检索器返回的5个文档片段里4个在讲公司历史1个模糊提到了“收入增长”那模型再厉害也巧妇难为无米之炊。关键点在于让检索为提取服务你需要调整检索策略使其更倾向于返回包含目标数据结构信息的文本。例如优化检索查询不要直接用原始问题“总结Q3财报”去检索。可以将其重写为“Q3 revenue profit financial highlights numbers”这些关键词更可能命中包含数据的句子。使用摘要索引对于需要整体理解的文档如一份完整的财报可以考虑使用SummaryIndex让模型先看到文档的全局摘要再进行提取这有助于理解数据的上下文关系。调整分块大小和重叠对于表格数据或密集数据段落适当增大文本分块chunk的大小并设置重叠overlap可以避免关键数据被割裂在不同的块中。3.3 处理模型的“不听话”与边界情况即使做了上述工作模型偶尔还是会输出不符合要求的格式。这时需要一套应对策略。重试与降级最简单的策略是设置自动重试。当Pydantic解析失败时捕获验证异常将模型的原始输出和错误信息一起作为一个新的、更强调格式的提示词再次发送给模型。通常一两次重试就能解决问题。如果多次重试失败可以考虑降级到“引导式文本输出解析”的方案作为保底。提供示例在定义Pydantic模型时利用Field的examples参数提供一两个清晰的示例这对模型理解格式有奇效。温度参数将模型的温度temperature调低例如0.1或0可以减少输出的随机性使其更倾向于遵循指令格式。但这可能会牺牲一些创造性在提取任务中通常不需要创造性。4. 实操过程构建一个财报信息提取引擎让我们通过一个完整的例子将上述理论付诸实践。目标是构建一个能从上市公司财报PDF中自动提取指定季度关键财务数据并返回JSON的引擎。4.1 环境准备与依赖安装首先确保你的环境已就绪。除了LlamaIndex我们还需要文档加载器和解析器。# 核心依赖 pip install llama-index llama-index-llms-openai llama-index-readers-file pymupdf # 用于处理PDF也可以使用 llama-index-readers-pdf # 本例使用 pymupdf (fitz) 作为PDF后端速度较快这里选择llama-index-llms-openai因为我们使用GPT-4作为LLM引擎它在结构化输出上表现最稳定。如果你使用其他模型如Anthropic Claude或本地部署的Llama 3需要安装对应的集成包。4.2 文档加载与索引构建假设我们有一个名为q3_earnings_report.pdf的财报文件。from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.core.node_parser import SentenceSplitter from llama_index.core import Settings from llama_index.llms.openai import OpenAI import os # 1. 设置LLM os.environ[“OPENAI_API_KEY”] “your-api-key” Settings.llm OpenAI(model“gpt-4-turbo-preview”, temperature0.1) # 低温度保证稳定性 # 2. 加载文档 documents SimpleDirectoryReader(input_files[“./q3_earnings_report.pdf”]).load_data() # 3. 自定义文本分块策略 # 财报数据密集句子可能较长我们适当增大块大小并设置重叠以避免数据割裂 text_splitter SentenceSplitter(chunk_size1024, chunk_overlap200) nodes text_splitter.get_nodes_from_documents(documents) # 4. 构建向量索引 # 使用默认的OpenAI嵌入模型即可 index VectorStoreIndex(nodes)这里的关键在于chunk_size和chunk_overlap的设置。对于财报这种包含表格和连续数据的文档1024的块大小和200的重叠是一个不错的起点可以有效防止“营收”和对应的“数字”被分到两个不同的块里。4.3 定义Pydantic模型与查询引擎现在定义我们想要提取的数据结构并创建专门的查询引擎。from llama_index.core import PromptTemplate from llama_index.core.program import MultiModalLLMCompletionProgram from pydantic import BaseModel, Field from typing import List, Optional # 1. 定义精细化的数据模型 class FinancialMetric(BaseModel): name: str Field(description财务指标名称如 Total Revenue) value: float Field(description指标数值) unit: str Field(description单位如 million USD, %) change: Optional[float] Field(None, description同比或环比变化百分比) class QuarterlyReport(BaseModel): company: str Field(description公司名称) fiscal_quarter: str Field(description财政季度如 Q3 2024) reporting_period: str Field(description报告期如 Ended Sep 30, 2024) metrics: List[FinancialMetric] Field(description本季度关键财务指标列表) management_comment: Optional[str] Field(None, description管理层关于本季度业绩的简要评述) # 2. 创建Pydantic查询程序 from llama_index.core.program import LLMTextCompletionProgram program LLMTextCompletionProgram.from_defaults( output_clsQuarterlyReport, prompt_template_str“”” 你是一个专业的财务分析师。请从以下上下文信息中提取关于{company_name}公司{target_quarter}的财务报告数据。 上下文信息 {context_str} 请严格按照提供的QuarterlyReport Pydantic模型格式填充数据。 注意 1. 只提取上下文中明确提及的数据不要推断或计算。 2. 对于metrics字段请尽可能多地提取不同的财务指标如营收、净利润、毛利率、每股收益等。 3. 如果上下文中没有管理层评述management_comment字段可以留空。 “””, verboseTrue, ) # 3. 组装检索与查询流程 from llama_index.core import QueryBundle query_engine index.as_query_engine(similarity_top_k5) # 检索前5个相关片段 def extract_structured_data(company_name: str, target_quarter: str) - QuarterlyReport: # 步骤1检索相关上下文 query_str f“{company_name} {target_quarter} revenue profit earnings financial statements” retrieved_nodes query_engine.retrieve(QueryBundle(query_str)) context_str “\n\n”.join([n.node.get_content() for n in retrieved_nodes]) # 步骤2调用Pydantic程序进行结构化提取 result program( company_namecompany_name, target_quartertarget_quarter, context_strcontext_str ) return result # 4. 执行查询 try: report extract_structured_data(“Apple Inc.”, “Q3 2024”) print(report.json(indent2)) except Exception as e: print(f“提取失败: {e}”) # 这里可以加入重试逻辑或降级处理这段代码是核心。我们创建了一个LLMTextCompletionProgram它内部会处理如何将我们的Pydantic模型、Prompt模板和上下文结合起来发送给LLM并解析返回结果。prompt_template_str中的{context_str}、{company_name}等是占位符会在运行时被替换。4.4 结果后处理与验证程序返回的report已经是一个QuarterlyReport类的实例。你可以直接访问其属性也可以轻松地将其转换为字典或JSON。# 访问数据 print(f“公司: {report.company}”) print(f“季度: {report.fiscal_quarter}”) for metric in report.metrics: print(f“ - {metric.name}: {metric.value} {metric.unit}”) # 转换为JSON便于API返回或存储 import json json_output report.json() data_dict report.dict()为了确保数据质量你可以在FinancialMetric模型中添加更严格的验证规则例如使用Field(ge0)来确保营收不为负数或者在业务逻辑层对提取到的指标进行合理性检查例如净利润通常不会大于营收。5. 常见问题与排查技巧实录在实际操作中你一定会遇到各种问题。下面是我踩过坑后总结的一些典型问题及其解决方法。5.1 问题模型返回了文本但无法解析成Pydantic对象抛出验证错误。排查思路查看原始输出将verboseTrue设置为program的参数或者捕获异常后打印出LLM返回的原始文本。很多时候模型确实在努力遵循格式但在JSON字符串里多了个尾随逗号或者键名用了中文引号。检查Prompt你的Prompt是否足够清晰地强调了“必须输出JSON”对于复杂嵌套结构在Prompt中提供一个简明的示例One-shot learning效果极佳。简化模型如果模型一直无法理解复杂嵌套先尝试定义一个极其简单的、只有两三个扁平字段的模型看是否能成功。如果能再逐步增加复杂度以此定位是模型能力问题还是Prompt描述问题。切换模型如果用的是gpt-3.5-turbo尝试换成gpt-4或gpt-4-turbo。在结构化输出任务上GPT-4系列的表现通常远好于3.5。5.2 问题检索到的上下文不包含我需要的数据导致提取结果为空或不准确。排查思路检查检索结果在调用program之前先打印出context_str。看看检索器到底返回了什么。很可能你的问题“提取净利润”和文档中使用的术语“归母净利润”或“Net Income”不匹配。优化查询词不要用自然语言问题直接检索。像前面提到的将“苹果公司Q3营收多少”重写为“Apple Q3 2024 revenue total income financial statement”。可以尝试多个查询词变体然后合并检索结果。调整检索参数增加similarity_top_k例如从3调到10让更多相关片段进入候选池。也可以尝试不同的检索器比如BM25Retriever关键词匹配与向量检索结合进行混合检索。预处理文档如果PDF解析后格式混乱很多PDF如此数据散落在各处。考虑使用专门的PDF表格提取库如camelot、tabula先提取表格数据将其转换为Markdown或结构化文本再喂给LlamaIndex。这相当于提前做了一次信息结构化。5.3 问题处理速度慢尤其是处理长文档或多个文档时。优化技巧并行处理如果你需要从多个文档中提取相同结构的信息可以为每个文档启动独立的异步任务。LlamaIndex的查询引擎本身是同步的但你可以用asyncio和run_in_executor将其包装。缓存索引构建向量索引是耗时操作。一旦构建好一定要将其持久化到磁盘如使用index.storage_context.persist(persist_dir“./storage”)下次直接加载避免重复计算嵌入向量。精简上下文不是所有检索到的片段都同等重要。在将context_str传递给LLM前可以做一个简单的过滤或摘要。例如只选择与数字、百分比、货币符号高度相关的句子。使用更快的模型/嵌入如果对精度要求不是极致可以尝试gpt-3.5-turbo-instruct模型它在简单提取任务上速度更快。对于嵌入模型可以换用本地轻量级模型如BAAI/bge-small-en能极大加快索引构建和检索速度。5.4 问题输出结构对了但数值或事实有误幻觉。应对策略 这是RAG系统的核心挑战之一。结构化输出解决了格式问题但无法根治幻觉。增强检索质量这是根本。确保检索到的上下文足够相关和准确。可以尝试重新分块、优化嵌入模型、使用重排序技术。在Prompt中加强限制明确写上“只使用提供上下文中的信息不要使用外部知识”和“如果上下文没有明确提及就将对应字段设为null”。置信度评分与人工审核对于关键业务数据如财务数据可以设计一个简单的置信度评分机制。例如检查提取的数值是否在上下文中以完全相同的形式出现。对于低置信度的结果流转到人工审核环节而不是直接进入下游系统。后处理校验编写规则校验数据。例如检查同一份报告中营收是否大于成本季度数据是否在合理范围内等。6. 进阶与LangGraph结合构建结构化输出工作流最新的网络热词提到了llamaindex langgraph这指向了一个更强大的模式使用LangGraph来编排包含结构化输出的复杂、多步骤工作流。LangGraph允许你以图的形式定义AI智能体的执行流程其中每个节点可以是一个工具调用、一个条件判断或者一次LLM调用。想象这样一个场景你需要从一份混合了文本、表格和图表的年报中提取财务数据、总结业务风险、并生成一份投资建议摘要。单一Prompt很难做好所有事。这时可以用LangGraph节点A路由根据用户问题判断任务类型是数据提取、总结还是分析。节点B数据提取调用我们上面构建的PydanticProgram专门提取结构化的财务指标。节点C风险总结调用另一个LLM专门从“风险管理”章节提取关键风险点并以列表形式输出。节点D综合分析将节点B和C的结构化输出作为输入再调用LLM生成最终的投资建议摘要。在这个工作流中结构化输出节点B和C的结果成为了节点之间可靠传递的数据“管道”确保了整个复杂流程的稳定性和可维护性。LlamaIndex与LangGraph的集成使得定义这样的节点和边变得非常直观将一次性的大模型调用拆解成了可调试、可复用、可监控的标准化组件。这是将结构化输出能力从单点工具升级为系统工程的关键一步。