LLM JSON Schema 实战:如何让 AI 稳定输出财报收入、现金流和风险因素?
LLM JSON Schema 实战:本文拆解 AI 财报助手中的 JSON Schema 结构化输出设计,包括财务指标字段、风险因素字段、管理层表述字段、source page、confidence、evidence、null 值处理和 schema validation,解决大模型分析财报时的幻觉、漏字段和格式不稳定问题。
本文目录
如果你需要让 LLM 从财报中结构化抽取收入、现金流、风险因素和原文证据,应该把 JSON Schema 当成输出契约,而不是只依赖 Prompt 约束。生产级 Schema 应固定字段和类型,允许未披露值保留为 null,并保留 source_page、source_text、confidence 等证据字段,把财务指标、风险因素、管理层表述和人工复核问题分层建模。需要明确:Schema 约束的是输出结构,不证明数字、单位、期间或引用本身正确;结构化输出仍可能出现拒答、不完整响应或业务规则错误,必须执行原文证据核验和业务校验。
这篇只解决结构化输出层。完整工作流看 AI 财务自动化 Agent;源文档解析看 Financial Report PDF Table Extraction;异步任务服务看 AI Financial Report Task Queue;实际产品入口看 AI Finance Tool。
官方规范与实现文档
- JSON Schema Specification 2020-12:核对 JSON Schema Core 与 Validation 规范。
- OpenAI Structured Outputs:核对受支持的 Schema 子集、拒答/不完整响应处理及业务校验边界。
如果这套 JSON Schema 要进入生产 Agent,不要只验证“JSON 能不能解析”。还要把字段级证据、null、置信度和人工复核结果接入 AI Agent Evaluation 与 AI Agent Observability,分别衡量抽取正确率、失败类型和运行链路,避免把结构合法误判成业务正确。
结构化输出的能力边界
JSON Schema 负责描述数据结构、类型和约束;模型 API 的 Structured Outputs 可以在支持的子集内约束输出遵循 Schema,但不能替代事实核验。以 OpenAI 官方文档为例,应用仍需处理 refusal、不完整响应和 API 错误,并验证 Schema 未表达的业务规则。对于财报数据,必须把公司主体、报告期间、币种、单位、GAAP / Non-GAAP 口径及原文页码分别校验;confidence 是模型给出的辅助信号,不是统计学置信区间,也不能代替人工复核。
本文解决的问题
- 大模型抽取财务指标时容易把 Non-GAAP 和 GAAP 混淆,甚至丢失单位、年份或合并口径。
- 模型在面对财报中没有披露的数据时,倾向于使用常识或模糊的推算公式进行猜测和脑补数字。
- 风险因素和管理层讨论表述被大模型过度压缩为无价值的套话,失去了微观语气变化的敏感性。
- 模型输出的 JSON 格式在生产环境下容易因为引号截断、多余逗号或解释性前言而导致解析报错。
适合谁读
- 正在开发 AI Agent、RAG 应用并面临非结构化文本中高精度数据提取痛点的全栈工程师。
- 希望借助大模型工具提升财报分析效率,但又对 AI 的胡说八道和数据准确性抱有强烈疑虑的投资研究员。
- 关注大模型 Structured Output 稳定度保障方案、校验拦截以及容错兜底机制设计的技术架构师。
本文在工具链中的位置
这篇文章只解决结构化输出和 JSON Schema 约束。PDF 表格抽取看 Financial Report PDF Table Extraction;异步任务服务看 AI Financial Report Task Queue;产品入口看 AI Finance Tool。
结构化复核字段
上线前建议保留 source_page、evidence、confidence、review_status 和 null_reason,让每个结论都能回到原文位置、证据片段和人工复核状态。
财报分析不能让 LLM 自由输出的原因
自由的自然语言输出会让财务分析系统失去最基础的可验证性和程序化处理能力。
北京六月的午后热得像个烤箱,我把室内的格力空调开到26度,手边放着一瓶刚从冰箱拿出来的3元冰红茶。显示器上,英伟达和微软的几百页财报PDF堆在一起。在研发AI财报分析系统时,真正折磨我的并不是文本的读取,而是大模型输出的多样性和不可靠性。
如果让大模型自由回答“总结一下这家公司的收入、现金流和风险因素”,通常会得到一段看起来流畅但毫无标准的自然语言。例如,它可能会把经营活动现金流量净额与自由现金流混为一谈,或者把财务报告里的上年同期数据套用在今年。更糟糕的是,它甚至可能把 FY2024 的第四季度数字看成是全年的数字。
自由输出的另一个致命问题在于“格式漂移”。在构建自动化分析流时,后台的数据库需要接收固定的字段值来进行绘图或做量化打分。如果模型这一次输出的是一个 markdown 表格,下一次输出的是一串 key-value 键值对,再下一次在 JSON 外部包裹了 json ... ,那下游的解析解析器就会直接抛出 JSONDecodeError。
因此,在严肃的投研场景下,我们必须强行收窄模型的表达范围,将它从“畅所欲言”约束到“格式定义”。这就是 JSON Schema 的底层价值。它不仅仅是前端展示的约定,更是整个 AI 财报抽取管线的数据契约。
财报结构化输出需要哪些模块?
将财报输出拆解为财务指标、风险因素、管理层语气和复核清单四个核心模块是实现系统稳定性的关键。
财报抽取 Schema 通常适合将公司元数据、财务指标、风险因素、管理层表述和复核问题分层组织,以便分别校验。下面给出一种可供实现参考的结构,不代表 XBSTACK 后端已经部署了该 Schema:
{
"company_metadata": {
"company_name": "NVIDIA Corporation",
"report_period": "FY2024",
"reporting_currency": "USD"
},
"financial_metrics": {},
"risk_factors": [],
"management_tone": [],
"review_questions": []
}
这里面的每一个子模块都承载着特定的数据约束逻辑。
第一,company_metadata 模块用于校验报告的归属性。大模型有时候会在长文本处理中发生注意力转移,如果分析的是英伟达的 PDF,却在上下文里读到了竞争对手的某些数据,模型可能会把这些数据杂糅在一起。通过在最外层限定元数据,可以强迫模型首先对公司主体和报告周期进行锁定。
第二,financial_metrics 模块,针对收入、毛利、运营开支、净利润、经营现金流、自由现金流等核心财务指标进行精确提取。
第三,risk_factors 模块,捕获财报中通常长达几十页的风险警告,并将其提取为可比对的特征字典。
第四,management_tone 模块,追踪管理层对于业务展望的微妙措辞改变。
第五,review_questions 模块,由 AI 生成的审计问题,作为人工复核的起点。
financial_metrics:财务指标的精确定义
财务指标抽取必须采用对象化封装,将数值、单位、周期与来源页面和原文强行绑定。
很多开发者在设计财务指标 Schema 时,喜欢使用扁平的键值对。例如,把收入定义为 “revenue”: 60922。这在实际中是个巨大的隐患。
因为 60922 这个数字本身是单薄的。它在财报里的单位是百万还是千?它的核算期间是截至 1 月 28 日的年度还是特定的季度?它出自 PDF 的哪一页?它的原始上下文是什么?
为了解决这个问题,所有 financial_metrics 成员都应定义为独立对象。财务金额和比率不宜先存为 binary float;Schema 可以保留原文十进制字符串,应用层再使用 Decimal 做精确解析和运算。以下是使用 Python 的 Pydantic 库对指标 Schema 的建模示例:
from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Literal
class MetricDetail(BaseModel):
value: Optional[str] = Field(
default=None,
description="原文数值的十进制字符串;应用层使用 Decimal 解析,未披露时填 null,不要先转换为 binary float"
)
unit: Optional[str] = Field(
default=None,
description="单位,例如 USD million, CNY thousand 等,须与原文一致"
)
period: Optional[str] = Field(
default=None,
description="对应的财务期间,例如 FY2024, Q4 FY2024 等"
)
source_page: Optional[int] = Field(
default=None,
description="该数据在原始 PDF 文件中的绝对页码"
)
source_text: Optional[str] = Field(
default=None,
description="抽取该数据所依据的财报原始句子或表格行文本"
)
confidence: Literal["high", "medium", "low"] = Field(
default="low",
description="置信度。若数据来源于表格且上下文清晰,选 high;若需要推导或上下文模糊,选 medium/low"
)
class FinancialMetrics(BaseModel):
revenue: MetricDetail = Field(description="营业收入")
gross_margin: MetricDetail = Field(description="毛利润率")
net_income: MetricDetail = Field(description="净利润")
operating_cash_flow: MetricDetail = Field(description="经营活动现金流")
free_cash_flow: MetricDetail = Field(description="自由现金流,指经营现金流减去资本支出,需寻找官方披露或明确说明")
在这套结构下,我们拿到的不再是单纯的数值,而是一个自带证据链的数据集。
比如,在调试英伟达 FY2024 的财报时,如果模型抽取的 Gross Margin 发生了 Non-GAAP 与 GAAP 的混淆,我们在校验 source_text 时,就会清晰地发现它读取的是 Non-GAAP 的 76.0% 还是 GAAP 的 72.7%。通过追溯 source_page,分析师可以一键跳转到 PDF 的相应位置,让 AI 的输出处于完全可追溯的状态。
为什么缺失字段必须输出 null?
在财报分析中保留不确定性远比强行填满字段重要,null 状态是防止 LLM 脑补公式和数据幻觉的第一道防线。
在传统的软件工程中,我们总是设法让每个字段都有确定值。但 AI 财报分析的逻辑刚好相反。
如果某家公司在财报里没有单独披露自由现金流 (Free Cash Flow) 这个指标,或者该季度没有给出资本支出的明细,我们该怎么办?
如果你的 Schema 不允许 null,或者 Prompt 里没有做出严厉约束,大模型通常会表现出强烈的“讨好倾向”:它会根据现有的数据自行计算。它会用经营现金流减去购建固定资产等支出来拼凑出一个自由现金流,或者干脆根据上个季度的数据按比例捏造一个。
这种做法极其危险。因为财报中自由现金流的计算方法在不同的公司里有不同的口径。有的公司在计算自由现金流时会扣除非控股股东的利息,有的公司则会加上资产处置收回的现金。AI 自作聪明的“脑补”,直接破坏了财务数据的严谨性。
因此,在 Schema 的定义中,除了必需的 metadata 外,其他字段的 default 值都应该设为 None,并且在描述里反复叮嘱:
[如果该指标在文本中未直接提及或无法直接推断,必须且只能将其设为 null。绝对不能进行公式估算或背景推论。]
这样,当我们在前端收到 null 时,就知道这是一个“未披露”信息,而不是大模型胡乱算出来的一个假警报。
如果你想直接测试 AI 财报助手,可一键跳转试用
支持 PDF 批量上传、管理层 Guidance 情绪审计、核心 KPI 指标抽取,免费免登录。
risk_factors:风险因素不要只做摘要
风险因素需要通过类型枚举、严重程度分级和原文证据链进行多维度结构化抽取,以便后续进行公司间的纵向与横向对比。
通常财报中的 Item 1A (Risk Factors) 部分包含了上万字的内容。大部分 AI 工具的做法是“精简总结”,最后输出一个段落摘要。
这种摘要读起来很省事,但实际上把最有价值的微观变化抹杀掉了。
如果一家半导体公司在今年的财报中,把“地缘政治导致供应链中断”的语气从“可能会影响”修改成了“已经产生实质性延误”,这就是一个强烈的风险升级信号。如果只看自然语言摘要,两者都会被归结为“面临供应链风险”,细微但关键的警示信息就此丢失。
我们可以将风险因素的设计扩展为多维的列表元素:
class RiskFactor(BaseModel):
risk_type: Literal[
"customer_concentration", # 客户集中度
"supply_chain", # 供应链风险
"regulation", # 监管风险
"currency_fluctuation", # 汇率风险
"litigation", # 诉讼风险
"inventory_impairment", # 存货减值风险
"debt_solvency", # 债务偿付风险
"competition", # 行业竞争
"macro_economy", # 宏观经济
"other"
] = Field(description="风险类型分类")
risk_summary: str = Field(description="用精炼的单句概括该风险的实质")
severity: Literal["critical", "high", "medium", "low"] = Field(description="该风险对公司业绩的潜在负面冲击程度")
is_new_or_intensified: bool = Field(description="该风险相比上期是否为新出现的,或者措辞有显著加重趋势")
evidence: str = Field(description="财报原文中关于该风险演变的具体事实陈述")
source_page: int = Field(description="该风险在财报 PDF 中的页码")
有了这样结构化的列表,我们就可以对不同年份的同一家公司进行字段对比。
如果 is_new_or_intensified 返回为 True,说明这是一个本期新增或加剧的风险;如果 risk_type 指向 customer_concentration,而对应的 evidence 提到“单一客户占比达到了 15%”,这种物理数据就能立刻引起研究员的警觉。
management_tone:管理层语气如何结构化?
管理层语气的提取必须基于措辞在上下文中的客观变化,而不是对大模型进行主观的情绪分类。
在 MD&A (Management’s Discussion and Analysis) 章节,管理层的措辞变化代表了他们对未来的实际态度。
由于大模型天生具有语义理解能力,我们如果只问它“管理层态度好不好”,它通常会回答“态度乐观”。因为财报公关稿通常会用很多类似 strong, progress, commitment 等正面词汇。
为了提取出真实的态度转变,我们需要在 Schema 里采用“双重措辞验证”结构:
class ToneAnalysis(BaseModel):
topic: str = Field(description="讨论的主题,例如 demand, pricing_power, capital_expenditure 等")
current_statement: str = Field(description="本期管理层的表述摘要")
tone: Literal["positive", "neutral", "cautious", "negative"] = Field(description="管理层对该主题的语气")
change_from_previous: str = Field(description="与此前已知表述相比,态度是转为谨慎、保持平稳还是更加乐观")
evidence: str = Field(description="原文中支撑该语气判断的最具代表性的一句话")
source_page: int = Field(description="对应的页码")
例如,当管理层在讨论 demand (需求) 时,本期表述是 Customers are becoming more cautious with their budgets,语气被模型评定为 cautious。在与上期的 change_from_previous 对比中,系统会记录下转为谨慎这个趋势。
通过这种方式,我们避开了 LLM 的主观臆测,强迫模型用原文证据 (evidence) 和具体的语义流向去支撑它的分类。
review_questions:最终输出应该是复核清单
AI 在严肃的投资研究中不应当充当最终决策者,而应当输出可供分析师人工核实的复核清单。
一种需要避免的设计,是让 AI 财报分析系统在结果末尾直接输出交易方向判断。结构化抽取和风险提示不应被包装成自动买卖指令;是否采取投资行动应由用户在核验原始披露和自身约束后独立决定。
首先,大模型不具备实时市场宏观感受,更容易在复杂的行业博弈中被财报里的官方措辞蒙蔽。
其次,直接给出交易决策会把系统推入极其复杂的合规和赔偿纠纷中。
AI 财报分析最好的终点,不是给结论,而是给复核清单 (Review Checklist)。
我们可以设计一个 review_questions 模块,让 AI 在抽取完全部数据后,自动生成 3 到 5 个针对该公司的批判性审查问题:
class ReviewQuestion(BaseModel):
question: str = Field(description="需要人工介入复核的关键财务或运营问题")
why_it_matters: str = Field(description="为什么这个问题对当前估值或风险判断非常关键")
related_metrics: List[str] = Field(description="与此问题关联的财务指标键名列表")
source_pages: List[int] = Field(description="建议分析师去阅读的财报 PDF 原始页码列表")
比如,当 AI 发现公司的营收增长了 20%,但经营活动现金流量净额却下降了 15% 时,它会在复核清单中生成这样一个问题:
[公司净利润与经营活动现金流走势出现背离,应收账款和存货是否存在异常积压?这可能会影响未来几个季度的现金流周转。建议重点核实 PDF 第 68 页的 Accounts Receivable 变动和第 72 页的 Inventory 减值准备。]
这样,AI 并没有越俎代庖去替人做交易决定,而是扮演了一个极其敏锐的助理角色,帮分析师把厚厚的财报压缩成了几条最值得推敲的线索。
常见异常形态(示例)
在生产环境中使用结构化输出时,需要考虑拒答、不完整响应、API 错误、字段类型或枚举校验失败等情况。下面的报错片段是用于说明异常形态的示例,不代表来自 XBSTACK 生产日志。
即使使用结构化输出,应用仍必须处理拒答、不完整响应和 API 错误。下面的片段仅用于演示异常形态,不是 XBSTACK 生产日志,也不应据此推断发生过真实线上故障。
ValidationError: 1 validation error for FinancialReportSchema
risk_factors -> 0 -> severity
Input 'high_severity' is not a valid enum member (should be one of: 'critical', 'high', 'medium', 'low')
或者这种由于模型输出被提前截断导致的 JSON 解析异常:
JSONDecodeError: Expecting ',' delimiter: line 42 column 18 (char 1289)
优先使用 OpenAI Python SDK 的 chat.completions.parse(),将 Pydantic 模型作为 response_format。SDK 会据此生成受支持的 JSON Schema,并把响应解析为类型化模型。应用仍需显式处理拒答、不完整响应和 API 异常;不要把拒答或截断内容无限拼回 Prompt 重试。
下面是一个精简示例。字段结构仅作演示,接入具体财报业务时仍须按披露口径扩展模型,并对金额、期间、币种和原文页码做独立校验:
from openai import OpenAI
from pydantic import BaseModel, ValidationError
class FinancialMetric(BaseModel):
name: str
value: str | None = None
unit: str | None = None
period: str | None = None
source_page: int | None = None
source_text: str | None = None
class RiskFactor(BaseModel):
category: str
summary: str
evidence: str
source_page: int | None = None
class ReviewQuestion(BaseModel):
question: str
why_it_matters: str
source_pages: list[int]
class FinancialReportSchema(BaseModel):
company_name: str
report_period: str
currency: str
financial_metrics: list[FinancialMetric]
risk_factors: list[RiskFactor]
review_questions: list[ReviewQuestion]
client = OpenAI()
def extract_financial_data(prompt: str):
try:
completion = client.chat.completions.parse(
model="gpt-4o-2024-08-06",
messages=[
{
"role": "system",
"content": (
"Extract only information supported by the supplied report. "
"Use null for undisclosed optional values. Never invent figures."
),
},
{"role": "user", "content": prompt},
],
response_format=FinancialReportSchema,
)
choice = completion.choices[0]
message = choice.message
if message.refusal:
return {"status": "refused", "reason": message.refusal}
if choice.finish_reason == "length" or message.parsed is None:
return {"status": "needs_human_review", "reason": "incomplete_or_unparsed"}
return message.parsed
except ValidationError as exc:
return {"status": "needs_human_review", "validation_errors": exc.errors()}
except Exception as exc:
# Production code should log a redacted error and classify retryable API failures.
return {"status": "api_error", "error_type": type(exc).__name__}
这里由 SDK 的解析辅助方法执行 Pydantic 解析;示例分别处理拒答、长度截断/未解析、模型校验异常和 API 异常。生产系统还应根据错误类型实施有上限的重试、幂等控制、脱敏日志和人工复核,而不是把所有异常都当作格式错误自动重试。
对比块 (Comparison)
Schema 约束输出可以比单纯 Prompt 指令更可靠地执行受支持的结构要求,但不能据此得出它在所有场景都优于 Function Calling,也不能保证事实错误更少。实际延迟和正确性取决于 Provider、模型、Schema 和应用实现。
以下是定性工程对比,并非实测 Benchmark。System Prompt、Function Calling 和 Schema 约束输出解决的问题不同,各自存在不同的失败模式。没有在相同模型、Prompt、Schema、工作负载和运行环境下测试,就不能给出通用的幻觉率或延迟排序。
对于财报抽取,应分别比较 Schema 校验通过率、字段级准确率、证据页准确率、拒答/不完整响应处理、端到端延迟和集成复杂度。下面的内容是需要在目标环境验证的设计权衡,不是 XBSTACK 已发布的实验结果:
-
方案一:纯 System Prompt 提示词约束
- 格式稳定度:Prompt 指令本身不能强制机器可校验的 Schema;字段遗漏和额外文本必须由应用层检测。
- 语义风险:如果没有明确约定 unknown/null,模型可能猜测缺失值;应通过人工标注测试集评估。
- 延迟:没有独立的 Schema 处理阶段,但端到端延迟仍取决于模型、Prompt 和输出长度。
- 代码集成难度:低。只需要写好 Prompt 即可,不依赖特定 SDK。
-
方案二:大模型 Function Calling (Tool Call) 约束
- 格式稳定度:工具参数可以按声明的参数 Schema 校验,但仍受 Provider 支持的 Schema 子集和应用层校验影响。
- 语义风险:参数格式合法不代表字段值正确;required 字段也不能证明事实准确。
- 延迟:应测量完整工具工作流,包括工具选择、参数生成和后续执行。
- 代码集成难度:中等。需要解析 message.tool_calls 并做后续反射。
-
方案三:原生 JSON Schema 约束 (Structured Output)
- 格式稳定度:结构化输出/受约束解码可以显著减少 JSON 语法和 Schema 形状错误,但不能把“格式符合 Schema”写成固定 99.9% 准确率,更不能等同于金额、单位、页码或财务语义正确。应分别统计 Schema 校验通过率、字段抽取准确率和证据映射正确率。
- 数据语义错误:Schema 只能约束字段类型、枚举和必填关系,不能阻止模型填入“格式合法但事实错误”的金额、日期或单位。应允许
null/缺失值并要求source_page/evidence,再用规则与人工抽样验证。 - 延迟:部分 Provider 对新 Schema 的首次请求可能产生额外处理开销,后续请求可能受益于缓存;应分别测量首次请求和稳定运行阶段。
- 代码集成难度:高。需要严格撰写 Pydantic 类并将其序列化为符合 OpenAI 或 Gemini 标准的 schema 字典。
对于财报抽取,当 Provider 支持所需的 Schema 子集时,结构化输出很有价值,但并非所有任务都适合采用同一种输出约束方式。应同时处理拒答和不完整响应,校验原文页码、会计/业务规则,建立回归评测并保留人工复核。Schema 符合率必须与事实准确率分开报告;没有实测证据时,两者都不能描述为百分之百。
准备好分析你的第一份财报了吗?
当前公开工具支持输入股票代码查看公开财务指标与风险摘要,暂不支持上传 PDF;本文的 PDF 解析、证据链与复核清单属于工程设计和研发方向。
FAQ
为什么 AI 财报分析需要 JSON Schema?
JSON Schema 可以约束大模型输出字段和格式,减少幻觉、漏字段和格式漂移,让收入、利润、现金流、风险因素和复核问题以稳定结构返回。如果没有 Schema,大模型输出的非结构化文本将无法被后台数据库直接利用,也无法进行跨公司的量化对比。
为什么缺失的财务数据必须输出 null 状态?
因为财报中没有明确披露的数据不能让模型猜测。输出 null 可以保留不确定性,避免模型编造数字或由于粗暴推算公式导致错误结论。这在数据源头就隔离了 AI 的脑补幻觉,确保了数据的绝对严肃。
source_page 和 source_text 这两个字段为什么是强制性的?
它们将 AI 的抽取结论与原始财报 PDF 的真实位置和原文段落进行强行绑定。当分析师怀疑 AI 的数据有误时,可以通过 source_page 和 source_text 快速回到财报的物理现场进行人工比对,这解决了大模型黑盒输出、无法复核的硬伤。
AI 财报助手能不能直接作为交易信号?
不能。AI 财报助手只适合做信息压缩、结构化抽取和复核清单生成,不具备电竞式宏观感知和即时情绪判断能力。它不能预测股价,也不能直接给出买入或卖出的投资建议,只能为人类分析师做辅助降噪。
继续阅读
如果你对财报解析的其他环节感兴趣,可以继续阅读我的这一系列实践总结:
- 前一阶段关于如何将表格完美录入的实战:财报 PDF 表格解析实战:如何避免 AI 把收入、现金流和风险因素看错?
- 后台系统是如何协同工作的架构拆解:AI 财报异步任务队列:任务流、结构化抽取与复核链路
- 教你如何使用开源工具从零搭建起这条自动化管线:用 AI 分析财报的 7 个步骤:从 PDF 到风险检查清单
把这篇文章里的财报抽取逻辑,放进爱财报工具里跑一遍
AI 财报文章统一导向工具页:上传财报、查看 JSON Schema、source_page、evidence 字段和人工复核流程。该工具只做信息压缩和结构化分析,不构成投资建议。
下一步:把工作流做成可运营系统
完整专题路径 →继续补 Retry、Queue、幂等、可观测性或成本控制,让流程不只“能跑”。
参与讨论
问题、验证与勘误
登录后可发表评论。所有新评论先进入审核;审核期间仅评论者本人和管理员可见,通过后才公开。