AI 财报助手任务队列:PDF 解析、超时与进度恢复

财报 PDF 解析什么时候使用异步任务队列?拆解上传、Worker、Checkpoint、幂等重试、进度回传和人工复核,澄清同步接口并非必然 504。

发布 · 2026-06-2415 分钟阅读XBSTACK 原创
Evidence 4 条资料来源
本文目录

AI 财报助手任务队列设计:当 PDF 解析与模型调用超出请求窗口时,如何用持久 Job、状态机、进度回传、授权范围内的缓存、幂等重试和人工复核控制风险?本文是可参考的系统设计,当前公开财报工具仅支持股票代码查询,尚不提供 PDF 上传。

本文解决的问题

  • 哪些 PDF 财报分析流程适合同步请求,哪些需要可恢复的异步任务?
  • 如何科学地将一份财报分析任务拆分为多阶段的状态机,避免处理流程成为黑盒?
  • 生产级的 Job 任务数据表该如何设计?字段该如何配置?
  • 如何优雅地在前端与后端之间实现处理进度的低延迟回传?
  • 面对 PDF 损坏、LLM 超时、限流(429)和 Schema 校验失败,该如何设计差异化的指数退避重试策略?
  • 如何防止用户重复上传相同财报文件造成的 API 算力浪费?
  • 哪些低置信度的异常结果必须被物理拦截并路由至人工复核队列?

适合谁读

  • 后端架构师:正在设计高吞吐、长耗时的 AI Agent 工作流后端处理系统。
  • AI 系统研发人员:急需解决 RAG 系统或长文本抽取管道中的超时与队列积压故障。
  • 全栈工程师:计划开发面向投研、审计的 serious AI 工具,寻求架构闭环方案。
  • 独立开发者:寻找降低大模型 API 费用、提升 RAG 响应体感的系统级缓存与去重设计。

一、 财报 PDF 何时需要异步任务队列?

讨论 PDF 财报分析队列时,应先区分架构设计与本站已上线功能。一种常见 Demo 会让前端上传 PDF、后端同步解析和调用模型;当任务耗时长、需要恢复或存在并发峰值时,才需要评估持久任务队列。当前 XBSTACK 公开财报工具并未上线 PDF 上传与完整 Worker 管线。

财报 PDF 解析与多轮模型调用可能持续数秒至数分钟,但同步接口并不会“几乎 100%”返回 504。实际超时取决于请求耗时、代理超时配置、ASGI/Worker 并发、模型限流和网络条件。短且有界的处理可以直接请求完成;需要独立扩容、进度跟踪或断点恢复的任务更适合使用持久队列。

因为一份标准的财报 PDF(例如 NVIDIA 的 10-K 年报)通常有上百页,包含密密麻麻的财务表格和备注说明。后端系统在接收到文件后,需要先调用 PDF 解析器进行物理定位,把里面的复杂多栏表格提取出来;接着还要进行文档分块(Chunking),然后将这些上下文分批次喂给大模型;大模型需要生成长达数页的结构化 JSON。在这期间,网络抖动、模型 API 限流(Rate Limit)、以及复杂的 JSON Schema 强校验,都会让整个处理过程耗时几秒、几十秒,甚至几分钟。

更让人抓狂的是,如果采用同步接口,用户在那看着网页转圈圈,心里完全没底,不知道后台是卡在 PDF 解析了,还是在调大模型,还是网络断开已经崩溃了。因此,当分析时间可能超出请求窗口,或任务需要取消、恢复和独立扩容时,可将上传与处理分离为持久任务记录和 Worker。进度更新时效需要根据推送、轮询间隔和实际队列负载测试,不能承诺固定秒级反馈。

二、 一个财报分析任务应该拆成哪些阶段

异步设计的核心是建立精细的状态机。

我们不能简单地把任务状态设为「处理中」和「已完成」,而是必须把财报处理流水线拆解为详细的状态节点,让用户和监控系统随时掌握任务所处的物理位置。下面是可复用的教学状态机示例;状态粒度、事务边界和最终取消/失败状态应根据实际任务调整,不代表本站已有生产部署或固定使用十个阶段:

CREATE TYPE job_status AS ENUM (
    'uploaded',                  -- 文件上传成功,记录已写入数据库
    'queued',                    -- 任务已进入 Redis/RabbitMQ 消息队列排队
    'parsing_pdf',               -- Worker 节点已领任务,正在提取 PDF 纯文本
    'extracting_tables',         -- 正在进行物理表格定位与结构化提取
    'chunking_document',         -- 正在执行文本语义分块与向量检索准备
    'running_llm',               -- 正在调用大模型(LLM)提取指标与风险因素
    'validating_schema',         -- 正在对模型输出的 JSON 进行 Schema 格式强校验
    'generating_review_questions',-- 正在根据异常提取结果,生成人工复核问题
    'needs_human_review',        -- 数据置信度低,已物理熔断,等待分析师人工复核
    'completed',                 -- 任务全部完成,结果已持久化
    'failed'                     -- 任务失败,已记录异常日志
);

通过这套精细的状态划分,前端可以渲染出包含「正在解析 PDF」、「正在提取财务表格」、「正在调用 AI 深度分析」等具体步骤的进度条,用户的心理安全感会大幅提升。

三、 Job 数据表设计

一个高可用的任务队列系统,必须依赖一张设计严密的数据库底表来进行任务持久化和状态追踪。这不仅是为了在系统宕机时能够恢复任务,更是为了支持后续的性能审计与费用结算。

下面给出 financial_analysis_jobs 任务表的 PostgreSQL DDL 示意。实际系统还必须把用户和租户身份从服务端认证状态推导出来,并补充资源级授权、任务幂等键、状态迁移事务、唯一约束、取消/过期状态、审计和 RLS;仅有 tenant_id 字段和索引并不能防止越权:

CREATE TABLE financial_analysis_jobs (
    job_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id VARCHAR(100) NOT NULL,                                        -- 经服务端验证的租户
    user_id VARCHAR(100) NOT NULL,                                          -- 提交任务的用户 ID
    file_id UUID NOT NULL,                                                  -- 关联的物理文件 ID
    status job_status NOT NULL DEFAULT 'uploaded',                           -- 任务当前状态
    progress INT NOT NULL DEFAULT 0 CHECK (progress BETWEEN 0 AND 100),    -- 里程碑完成度,不是可靠的剩余时间百分比
    current_step VARCHAR(50) NOT NULL DEFAULT 'upload_success',             -- 当前执行的具体原子步骤
    error_code VARCHAR(50),                                                 -- 失败时的标准错误码
    retry_count INT NOT NULL DEFAULT 0,                                     -- 当前已重试次数
    model_version VARCHAR(50) NOT NULL,                                     -- 运行该任务的大模型版本
    prompt_version VARCHAR(50) NOT NULL,                                    -- 运行该任务的 Prompt 版本
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP WITH TIME ZONE
);

-- 为常用查询字段建立索引,保证大并发下的查询速度
CREATE INDEX idx_jobs_tenant_user ON financial_analysis_jobs(tenant_id, user_id);
CREATE INDEX idx_jobs_status ON financial_analysis_jobs(status);
CREATE INDEX idx_jobs_file_id ON financial_analysis_jobs(file_id);

四、 为什么要把 PDF 解析和 LLM 调用拆开

在系统架构层面,应把 PDF 解析和模型调用划分为可独立恢复、分别计量的步骤;这可以在单体 Worker、独立任务队列或微服务中完成,并非一律必须拆成两个物理服务。

解耦的根本原因在于,PDF 解析与 LLM 调用是两类截然不同的计算任务,且它们的故障率和错误特征完全不同:

  • PDF 解析是 CPU 密集型任务,主要消耗服务器本地计算资源,出错通常是因为 PDF 损坏、格式不兼容或者混入了大面积的扫描图片;
  • LLM 调用是网络与 I/O 密集型任务,主要消耗外部 API 额度(Tokens),出错通常是因为大模型提供商限流、网络连接超时、或者是输出格式不符合 JSON Schema 约束。

如果没有持久化的阶段性结果,模型调用失败后可能被迫重复 PDF 解析。关键不在于微服务数量,而在于保存可验证的解析中间结果、文件/解析器版本、授权范围和失败恢复点。对敏感财报要限制缓存读取权限与保留时间;重新请求 LLM 的延迟受上游恢复、限流和任务队列影响,不能保证“秒级重试”。

工程设计参考 / REFERENCE DESIGN

如果你想直接测试 AI 财报助手,可一键跳转试用

当前公开工具支持按股票代码查询公开财务指标与风险摘要;不支持 PDF 批量上传。本文的 PDF 队列是架构示例,不是已上线功能。

五、 进度回传方案对比:Polling vs SSE vs WebSocket

当任务进入异步处理后,前端需要实时获取处理状态。在实际工程落地中,我们有三种常见的通信方案。以下是它们在开发成本、确定性和实时体感上的对比。

评估维度轮询 (Short Polling)服务器发送事件 (SSE)双向通信 (WebSocket)
开发成本极低(前端写个简单的 setInterval 即可)中等(后端需要支持流式输出响应)高(需要管理长连接生命周期和心跳检测)
网络开销由轮询间隔、HTTP 连接复用与响应头大小决定常见为持续响应流,需心跳和重连长连接有握手和心跳开销
服务器负载与请求频率、缓存和数据库查询方案相关长连接数、代理资源和广播策略决定开销与连接数、消息频率和部署拓扑相关
单页路由适配简单(跳转时直接销毁 timer 即可)简单(路由切换时关闭 EventSource)复杂(跳转时需要处理连接断开与自动重连)
首选建议适合第一版快速上线,对并发要求不高的场景适合单向进度推送,是最推荐的平替方案适合需要复杂双向交互的交互式 AI 聊天台

在 AI 财报助手的架构设计中,第一版我建议采用「轮询(Polling)」或者「服务器发送事件(SSE)」。因为财报分析的进度是完全单向的(从 0% 到 100%),SSE 能够提供非常通畅的进度条跳动体验,且不需要像 WebSocket 那样维护沉重的双向连接管理和复杂的网关集群。

六、 失败重试策略设计

异步任务如果不设计容错,在生产环境会死得非常难看。我们必须根据不同的错误类型,设计针对性的指数退避(Exponential Backoff)重试策略,而不是盲目地死循环重试。

下面的 Python 代码演示安全可重试的只读/模型调用如何按异常类型有界退避,而非通过包含凭据或隐私数据的错误文本匹配 429。真实 Provider SDK 的 429、超时和 5xx 需由适配层明确转换为 RetryableUpstreamError 并处理 Retry-After;PDF 损坏或结构化校验失败应按任务规则直接失败或人工复核。代码不是已部署 Worker,不能拿去自动重试扣费、退款等有副作用操作:

import random
import time

class PermanentInputError(Exception):
    """PDF damaged, schema contract invalid, or manual review required."""

class RetryableUpstreamError(Exception):
    """Raised by an API adapter for a verified retryable 429/timeout/5xx."""
    def __init__(self, retry_after_seconds=None):
        super().__init__("TEMPORARY_UPSTREAM_FAILURE")
        self.retry_after_seconds = retry_after_seconds

def run_readonly_step(step, max_attempts=3):
    # Only for safe-to-retry read/model calls; not payments or external writes.
    if max_attempts < 1:
        raise ValueError("max_attempts must be >= 1")
    for attempt in range(max_attempts):
        try:
            return step()
        except PermanentInputError:
            raise  # Do not retry invalid PDFs or schema-contract violations.
        except RetryableUpstreamError as err:
            if attempt + 1 == max_attempts:
                raise
            delay = min(30.0, 2 ** attempt + random.uniform(0, 1))
            if err.retry_after_seconds is not None:
                delay = max(delay, max(0.0, float(err.retry_after_seconds)))
            # Long delays should be rescheduled by the durable task queue.
            time.sleep(delay)

七、 结果缓存和重复上传怎么处理

在严肃的生产环境中,大文件财报的 PDF 解析和 LLM 调用的费用是非常高昂的。如果用户重复上传同一个 PDF,或者多个用户在同一天上传同一份 NVIDIA 2024 年报,系统如果每次都重新解析,那就是在给大模型厂商送钱。

我们需要在架构上实现「物理去重与结果缓存」。

当用户上传 PDF 时,可以在受控后端计算其 SHA-256,随后在当前已授权的租户和用户范围内查找匹配项。仅有文件哈希匹配不意味着对方有权访问原件、解析文本或模型生成的财务结论;跨用户共享缓存要有独立的授权策略。下面是一个默认不跨用户复用的示意表:

CREATE TABLE financial_reports_cache (
    tenant_id VARCHAR(100) NOT NULL,
    user_id VARCHAR(100) NOT NULL,
    file_hash CHAR(64) NOT NULL,
    parser_version VARCHAR(50) NOT NULL,
    model_version VARCHAR(50) NOT NULL,
    prompt_version VARCHAR(50) NOT NULL,
    schema_version VARCHAR(50) NOT NULL,
    parsed_text_url VARCHAR(512),     -- Must also enforce ownership in object storage
    extracted_kpis JSONB,             -- Sensitive derived data; do not share by hash
    cached_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (
        tenant_id, user_id, file_hash,
        parser_version, model_version, prompt_version, schema_version
    )
);

去重处理逻辑如下:

  1. 在后端计算原文件 SHA-256,验证当前用户是否有权访问该文件与可能复用的解析结果;
  2. 同时核对 tenant_id、user_id、解析器/模型/Prompt/Schema 版本、有效期与撤销状态;跨用户即使哈希完全相同,也不能直接复用其私有结果;
  3. 仅当授权、版本和完整性校验全部通过时,才为新 Job 记录可审计的缓存命中与结果引用。缓存响应耗时受数据库、对象存储和负载影响,不承诺一定 1 秒内完成。

八、 哪些任务要进入人工复核队列

在投研和审计等严肃的财务场景下,我们不能完全寄希望于大模型输出 100% 的准确度。如果大模型输出的结果触发了我们设定的异常红线,系统必须执行物理熔断,把任务状态设为 needs_human_review,并路由到专门的人工复核后台。

下面六类情况是建议测试的人工复核触发条件,不是已经上线的 XBSTACK 财报任务队列策略:

  • 缺失证据页码:返回的财务 KPI 指标中,source_page 字段为 null 或小于等于 0;
  • 证据校验失败:模型返回了 evidence 原文,但我们去 PDF 对应的 source_page 中搜索该文本时,返回了 contains 校验失败;
  • 财务指标异常:同比变化剧烈、口径跨期不一致或负值出现时应核查原文;500% 等阈值需要根据科目、样本与风险基线校准,负收入也不能不看会计口径就直接判为非法;
  • 模型置信度:仅当置信度经过标注样本校准且与错误率存在明确对应关系时才作为触发信号;0.85 不是通用阈值;
  • JSON Schema 强校验失败,且在退避重试后依然无法生成合规格式;
  • 提取出的风险因素(Risk Factors)中,出现了系统黑名单里的敏感词或存在严重的语义冲突。

关于人工复核的具体 UI 交互和队列拦截机制,可以参考我之前在实验室里总结的:👉 Golden Dataset 评测体系 —— 学习如何设置可追溯的人工复核证据与评测流程;该链接并不代表真实的双盲生产链路已上线。

九、 接入 AI Financial Report Analyzer

异步任务队列可以作为 PDF 财报分析服务的一种技术基础。当前公开的 AI Finance 工具支持股票代码查询公开财务数据,尚不支持 PDF 上传;本文介绍的队列、PDF 解析和 Worker 流程属于工程设计示例,不代表 XBSTACK 已部署完整生产闭环:

下一步 / NEXT READING

准备好分析你的第一份财报了吗?

当前公开工具支持输入股票代码查看公开财务指标与风险摘要,暂不支持上传 PDF;本文的 PDF 解析、证据链与复核清单属于工程设计和研发方向。

常见问题解答

为什么不推荐用 Redis + Celery 的默认队列直接处理 PDF 解析?

Celery 并不禁止长任务混合排队,但需要评估 Worker 并发、任务时长和预取策略。官方文档说明,长任务可从 worker_prefetch_multiplier=1 开始校准;使用 task_acks_late 时还要保证重放安全和业务幂等。Celery 5.6+ 的 worker_disable_prefetch 只适用于 Redis Broker。对 CPU 密集型 PDF 与 I/O 密集型模型调用,可根据实际 P95 延迟和饥饿情况分开 Worker 池或队列;不应宣称默认配置必然内存泄漏,也不要求必须使用 RabbitMQ。

处理进度(progress 字段)在后台应该如何计算并更新?

我们不需要搞非常精确的动态时间估算,那在物理上是不准确的。推荐采用「里程碑式进度更新」。例如:文件上传成功为 10%,PDF 解析完成为 30%,表格抽取结束为 50%,LLM 推理中为 80%,Schema 校验通过为 95%,完全存入数据库后归档为 100%。这种分阶段的离散步长,实现起来最稳定,也最符合用户的直观体感。

如何防止在高并发下,长连接(SSE / WebSocket)把后端的 Express 或 Node 服务的文件描述符撑爆?

使用 SSE 时,长连接会占用客户端与服务端资源,但是否达到文件描述符上限取决于代理、HTTP 协议、连接池和并发配置。应在目标服务器的系统限制与压测结果下校准上限,不能机械执行 ulimit -n 65535 当作通用修复。前端离开页面时关闭 EventSource,服务端实现心跳、鉴权、断线重连和可恢复事件游标;任务长时间排队应通过任务状态和超时策略治理,而非擅自把 10 分钟排队当作失效。

继续阅读

工具入口 / AI Finance Tool

把这篇文章里的财报抽取逻辑,放进爱财报工具里跑一遍

AI 财报文章统一导向工具页:上传财报、查看 JSON Schema、source_page、evidence 字段和人工复核流程。该工具只做信息压缩和结构化分析,不构成投资建议。

下一步:把工作流做成可运营系统

完整专题路径 →

继续补 Retry、Queue、幂等、可观测性或成本控制,让流程不只“能跑”。

进入评测与可观测性AI 财报助手评测体系:如何用 Golden Dataset 发现 LLM 是否看错财报?AI 财报助手评测体系:本文拆解 AI 财报助手的评测体系设计,如何用 Golden Dataset、人工标注答案、Schema 校验、数值误差容忍、风险因素召回率和证据页码核对,判断 LLM 是否看错财报、漏掉风险或编造数字。同一专题的下一层问题LLM JSON Schema 实战:如何让 AI 稳定输出财报收入、现金流和风险因素?LLM JSON Schema 实战:本文拆解 AI 财报助手中的 JSON Schema 结构化输出设计,包括财务指标字段、风险因素字段、管理层表述字段、source page、confidence、evidence、null 值处理和 schema validation,解决大模型分析财报时的幻觉、漏字段和格式不稳定问题。继续处理状态与记忆AI 财报助手技术实现:如何把财报 PDF 拆成结构化风险检查清单?AI 财报助手技术实现:深入拆解 AI 财报助手的技术实现思路,包括 PDF 解析、章节切分、表格抽取、LLM 结构化抽取、JSON Schema 输出、风险因素提取、管理层语气分析以及人工复核清单生成。
评论与补充证据

参与讨论

问题、验证与勘误

登录后可发表评论。所有新评论先进入审核;审核期间仅评论者本人和管理员可见,通过后才公开。

登录评论 审核后公开
正在加载评论区…