1. 项目缘起：当PDF解析成为业务瓶颈

在数字化的业务流中，PDF文档处理是一个既常见又令人头疼的环节。我们团队负责一个数据聚合与分析平台，其中一个核心功能是自动解析来自不同供应商的24页标准化周报PDF，从中提取关键指标、图表数据和趋势分析，用于生成我们的内部商业洞察报告。最初，我们采用了一套基于传统OCR（光学字符识别）和规则模板的解析方案。这套方案在初期勉强能用，但随着供应商模板的微小调整、PDF生成质量的波动（比如扫描件清晰度、字体嵌入问题），以及我们自身对数据提取精度和字段覆盖范围要求的提升，问题开始集中爆发。

最典型的症状就是“超时”。一份24页的PDF，处理时间从预期的2-3分钟，逐渐恶化到10分钟以上，甚至频繁触发系统预设的15分钟超时限制，导致整个数据处理流水线堵塞。更糟糕的是，解析准确率无法稳定在95%以上，大量报告需要人工二次核对与修正，这直接抵消了自动化带来的效率红利。我们意识到，这不是简单的“优化代码”能解决的问题，而是整个技术栈在面对非结构化、多格式文档信息提取时的根本性局限。我们需要一个能理解文档语义、具备强大泛化能力，并且能在可控成本下规模化应用的解决方案。这就是我们转向探索大语言模型（LLM），并最终落地Gemini与OpenRouter组合方案的背景。

2. 技术选型：为什么是Gemini + OpenRouter？

面对PDF解析的难题，我们评估了数个方向。首先是继续深耕传统方案，比如采用更先进的OCR引擎（如Tesseract 5.0+，或商业化的Azure Form Recognizer、Amazon Textract），并结合更复杂的启发式规则与正则表达式。这条路的问题是维护成本指数级增长，每增加一个供应商或遇到一种新布局，就需要工程师投入大量时间编写和调试规则，系统脆弱且僵化。

其次是采用专为文档理解设计的LLM服务，比如 Anthropic Claude 对长文档的支持，或是 OpenAI 的 GPT-4 with Vision。它们能力强大，但成本是我们必须严肃考虑的因素。我们的周报是24页，包含大量表格和图表，如果直接将整个PDF的图片或提取文本丢给这些按Token计费的API，单次处理成本可能高达数美元，这对于每周需要处理上百份报告的我们来说是难以承受的。

我们的核心需求拆解如下：

1. 强大的多模态理解能力 ：必须能“看懂”PDF页面中的文字、表格结构、图表标题，并理解其上下文语义。
2. 可控的处理成本 ：需要在可接受的单次调用成本内（理想目标是低于1美元）完成24页内容的解析。
3. 稳定的性能与可用性 ：API响应时间需稳定，并且有可靠的服务保障。
4. 灵活的部署与集成 ：易于与我们现有的Python技术栈集成。

基于这些考量，我们选择了 Google Gemini Pro 1.5 与 OpenRouter 的组合。

为什么选择Gemini Pro 1.5？ Gemini 1.5 Pro 在当时（现在依然是）有一个杀手锏特性：超长的上下文窗口（最高可达100万Token）。这意味着我们可以将一份24页PDF转换后的文本（经过预处理压缩后）一次性送入模型，模型能够通篇理解整个报告的结构和前后关联。这对于提取需要跨页汇总或对比的数据至关重要。此外，Gemini在原生多模态理解（虽然我们主要用文本，但其对表格结构的理解优于纯文本模型）和代码生成能力上表现优异，后者可以帮助我们动态生成数据提取逻辑。

为什么引入OpenRouter？ OpenRouter本身不是一个模型，而是一个聚合了众多LLM API（包括Gemini、Claude、GPT等）的平台。它为我们提供了两个关键价值：

1. 成本优化与对比 ：OpenRouter提供了统一的计价方式（每百万Token），并允许我们轻松对比不同模型在相同任务上的效果和成本。我们可以先用小批量数据测试不同模型，找到性价比最高的那个。事实上，我们通过OpenRouter发现，在某些结构化数据提取任务上，一些较小的、更便宜的模型（如Claude Haiku）在简单页面表现不俗，这启发了我们后续的混合策略。
2. 冗余与降级保障 ：将OpenRouter作为调用中介，当Gemini API暂时出现高延迟或故障时，我们可以快速在OpenRouter面板上将请求切换到另一个备选模型（如GPT-4 Turbo），虽然成本可能变化，但保证了业务流水线的持续运行，这是一种高可用性设计。

注意 ：直接使用Google AI Studio或Vertex AI调用Gemini API是更直接的方式。但OpenRouter提供的灵活性和对多模型API的标准化封装，对于需要长期优化成本和应对模型服务波动的生产环境来说，是一个有价值的抽象层。

3. 架构设计与核心优化策略

单纯的“把PDF扔给LLM”不仅昂贵，而且低效。我们的核心优化思想是： 让LLM做它最擅长的事（语义理解、复杂推理、格式适配），而把繁重、规则明确、低成本的工作留给传统程序 。整个处理流水线被设计成一个多阶段过滤与精炼的过程。

3.1 整体处理流水线

我们的解析引擎工作流程如下：

1. PDF预处理与分页 ：使用 PyMuPDF (fitz) 或 pdf2image + pytesseract 进行初步文本和图像提取。这一步会生成每页的原始文本和页面图像（用于后续需要视觉理解的页面）。
2. 内容分类与路由 ：一个轻量级的本地文本分类模型（基于TF-IDF或小型BERT）或规则，对每一页进行初步分类。例如：识别出“封面页”、“目录页”、“执行摘要页”、“详细数据表页”、“图表页”、“附录页”。
3. 分层处理策略 ：
   • 简单/规则化页面（如封面、目录） ：使用预定义的正则表达式和解析器直接提取信息（如报告日期、公司名称）。完全绕过LLM，成本为零。
   • 复杂表格页 ：使用 Camelot 或 Tabula 尝试提取表格结构。如果提取成功且格式规整，则直接使用；如果表格跨页或格式扭曲，则将提取的文本和结构信息作为上下文，送入LLM进行修正和关系重建。
   • 图表与混合内容页 ：将页面图像和提取的文本一起，送入具备多模态能力的Gemini Pro，要求其描述图表趋势、提取图例数据，并将散落在文本中的关键指标关联起来。
   • 核心叙述与分析页（如执行摘要、趋势分析） ：将纯文本内容送入LLM，通过精心设计的提示词（Prompt），进行摘要、情感倾向判断、关键风险点提取等深度分析。
4. LLM调用优化 ：这是成本控制的核心。我们不是将整篇文档文本一次性送入，而是根据分类，只将 必要的页面 和 必要的上下文 送入LLM。例如，提取某个特定表格时，只附带其前后两页的文本作为上下文，而不是24页全部内容。同时，利用OpenRouter的流式响应和异步调用，处理多个页面的请求。
5. 结果后处理与合成 ：将从不同页面、不同处理路径提取出的数据片段，按照一个统一的JSON Schema进行组装、验证和关联。最后，生成一份结构化的数据报告。

3.2 提示词工程精要

LLM的表现极度依赖提示词。我们的提示词设计遵循以下原则：

• 角色定义清晰 ： 你是一位专业的数据分析师，擅长从商业报告中提取结构化数据。
• 任务指令明确 ： 请从以下文本中，提取所有关于“季度营收”的指标。以JSON格式输出，包含字段：metric_name (string), value (number), unit (string), period (string), page_number (integer)。
• 提供结构化示例 ：在提示词中给出1-2个输入输出的例子（Few-shot Learning），能极大提高模型输出格式的稳定性。
• 上下文管理 ：明确告诉模型哪些是需要关注的文本，哪些是辅助背景。例如： 以下内容摘自报告第5页，主要描述市场风险。请重点分析...，第4页的摘要部分仅供参考。
• 输出格式强制 ：除了要求JSON，我们还使用像 Pydantic 这样的库，在代码层定义响应模型，并在提示词中强调必须严格遵守此模型，否则进行重试。

一个用于提取表格数据的提示词示例：

你正在分析一份商业报告的PDF页面。以下是当前页面的文本内容，其中包含一个关于地区销售数据的表格。
---
[页面文本内容]
---
任务：
1. 识别并重建页面中的主要数据表格。
2. 将表格数据转换为一个JSON数组。
3. JSON数组中的每个对象对应表格的一行（标题行除外），属性名称为表格的列标题。
4. 确保数值字段被转换为数字类型，百分比字符串转换为小数（如“15%”转为0.15）。
5. 如果表格跨页，请根据上下文推断完整结构。

请仅输出JSON，不要有任何额外解释。

4. 实操：从PDF到结构化数据的核心步骤

下面，我将以一个具体的“地区销售业绩表”页面为例，拆解我们的实操步骤。

4.1 步骤一：PDF文本与元数据提取

我们优先使用 PyMuPDF ，因为它能保留部分简单的格式和位置信息，且速度极快。

import fitz  # PyMuPDF

def extract_text_with_fitz(pdf_path):
    doc = fitz.open(pdf_path)
    page_texts = []
    for page_num in range(len(doc)):
        page = doc.load_page(page_num)
        # 提取文本，并保留一些布局信息（如块）
        text = page.get_text("dict")  # 获取为字典结构，包含块、行、跨度信息
        # 或者使用纯文本，更快但信息少
        # text = page.get_text()
        page_texts.append({
            "page_num": page_num + 1,
            "text_dict": text,  # 复杂处理用
            "raw_text": page.get_text()  # 简单分析用
        })
    doc.close()
    return page_texts

对于 PyMuPDF 无法很好提取文本的扫描件或特殊格式PDF，我们启用备用方案： pdf2image + pytesseract 。

from pdf2image import convert_from_path
import pytesseract

def extract_text_with_ocr(pdf_path, dpi=200):
    images = convert_from_path(pdf_path, dpi=dpi)
    ocr_texts = []
    for i, image in enumerate(images):
        # 对图像进行预处理（灰度化、二值化、降噪）可以显著提升OCR精度
        # 此处为简化示例
        text = pytesseract.image_to_string(image, config='--psm 3')
        ocr_texts.append({"page_num": i+1, "raw_text": text})
    return ocr_texts

4.2 步骤二：基于规则与轻量模型的内容路由

我们维护一个页面分类器。初期使用关键词匹配：

def classify_page_by_keywords(text, page_num):
    text_lower = text.lower()
    if page_num == 1:
        return "cover"
    if "table of contents" in text_lower or "目录" in text_lower:
        return "toc"
    if "executive summary" in text_lower:
        return "exec_summary"
    # 通过寻找“Q1”、“Q2”、“Revenue”、“Sales”等关键词和数字表格模式来识别数据页
    if re.search(r'\b(Q[1-4]|Quarter\s*\d)\b', text_lower) and re.search(r'\$\d+\.?\d*\s*[MB]?', text):
        return "financial_table"
    return "narrative"  # 默认为叙述性页面

后期，我们训练了一个简单的文本分类模型（如使用 scikit-learn 的 TfidfVectorizer + LogisticRegression ），用几百个已标记的页面数据，就能达到95%以上的分类准确率，比规则更健壮。

4.3 步骤三：分层处理与LLM调用集成

这是核心环节。我们以“financial_table”类型的页面为例，展示如何集成OpenRouter调用Gemini。

首先，安装必要的库并配置OpenRouter（假设已获得API Key）。

import openrouter
import json
from pydantic import BaseModel, Field
from typing import List

# 配置OpenRouter客户端
client = openrouter.OpenRouter(api_key="your_openrouter_api_key")

# 定义我们希望LLM返回的数据结构
class SalesDataRow(BaseModel):
    region: str
    q1_sales: float
    q2_sales: float
    q3_sales: float
    q4_sales: float
    growth_rate: float  # 百分比，如0.15表示15%

class ExtractedTable(BaseModel):
    data: List[SalesDataRow]
    currency: str = "USD"
    fiscal_year: int

def extract_table_via_llm(page_text, context_text=""):
    """
    使用LLM解析表格页面
    :param page_text: 当前页的文本
    :param context_text: 前后页的补充文本，用于解决跨页问题
    """
    # 构建提示词
    system_prompt = """你是一个数据提取专家。你的任务是从提供的报告文本中，精确提取出地区销售数据表格，并输出为严格指定的JSON格式。"""
    
    user_prompt = f"""
    请分析以下商业报告页面内容，找出其中的地区季度销售数据表格。
    
    【当前页内容】
    {page_text}
    
    【相关上下文】
    {context_text}
    
    请提取表格数据，并按照以下要求输出：
    1. 识别表格的每一行数据（忽略表头）。
    2. 将每一行数据转换为一个对象。
    3. 对象字段必须包括：region (地区名), q1_sales, q2_sales, q3_sales, q4_sales (均为数值，单位是千美元), growth_rate (增长率，小数形式，如0.15代表15%)。
    4. 推断表格数据对应的财年。
    5. 最终输出一个JSON对象，包含 `data` (数组), `currency`, `fiscal_year` 三个字段。
    
    只输出JSON，不要有任何其他文字。
    """
    
    try:
        # 通过OpenRouter调用Gemini Pro
        response = client.chat.completions.create(
            model="google/gemini-pro-1.5",  # 指定OpenRouter上的模型标识
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_prompt}
            ],
            temperature=0.1,  # 低温度，确保输出确定性高
            max_tokens=2000
        )
        
        llm_output = response.choices[0].message.content.strip()
        
        # 尝试解析JSON
        result_dict = json.loads(llm_output)
        # 使用Pydantic模型进行验证和类型转换
        extracted_data = ExtractedTable(**result_dict)
        return extracted_data
        
    except json.JSONDecodeError as e:
        print(f"LLM返回了非JSON内容: {llm_output[:200]}...")
        # 可以在这里加入重试逻辑，或者使用更复杂的解析方法
        return None
    except Exception as e:
        print(f"调用API失败: {e}")
        return None

4.4 步骤四：结果验证与管道组装

从不同页面提取的数据需要被整合和验证。

def assemble_report(all_page_data):
    """
    all_page_data: 列表，包含从每一页提取出的各类数据片段
    """
    final_report = {
        "metadata": {},
        "executive_summary": {},
        "financial_tables": [],
        "key_metrics": [],
        "charts_analysis": []
    }
    
    for page_item in all_page_data:
        page_type = page_item.get("type")
        data = page_item.get("data")
        
        if page_type == "cover":
            final_report["metadata"].update(data)  # 合并日期、标题等信息
        elif page_type == "exec_summary":
            final_report["executive_summary"] = data
        elif page_type == "financial_table" and data:
            # 这里可以加入去重和合并逻辑，比如根据财年合并表格
            final_report["financial_tables"].append(data.dict())  # 假设data是Pydantic模型实例
        # ... 其他类型处理
    
    # 最终进行数据一致性校验
    # 例如，检查所有财务表格的货币单位是否一致
    currencies = {table['currency'] for table in final_report['financial_tables']}
    if len(currencies) > 1:
        print(f"警告：发现多种货币单位 {currencies}，请人工复核。")
    
    return final_report

5. 性能对比与成本效益分析

优化前后的对比是惊人的。

优化前（传统OCR+规则方案）：

• 平均处理时间 ：8-12分钟/份
• 成功率（无需人工干预） ：约70%
• 单份直接成本 ：主要为服务器计算资源，约$0.05
• 隐性成本 ：工程师每周约10小时维护规则；数据分析师每周约5小时人工校正。

优化后（Gemini+OpenRouter混合策略）：

• 平均处理时间 ：降至45-90秒/份。主要耗时在LLM API调用（网络I/O），本地处理极快。
• 成功率 ：提升至98%以上。LLM对模糊和变体的处理能力远超规则。
• 单份直接成本 ：这是核心。通过分层策略，我们平均每份报告只将约6-8页（主要是复杂表格和核心分析页）的内容发送给LLM。经过提示词优化和上下文裁剪，平均每份报告的Token消耗在25K左右（输入+输出）。通过OpenRouter调用Gemini Pro，成本约为 $0.15 - $0.25/份 。
• 隐性成本 ：工程师维护时间减少80%，主要用于优化提示词和分类模型；数据分析师几乎无需校正。

结论 ：单份报告的直接成本从$0.05上升至约$0.20，增加了$0.15。但是，我们节省了每周至少15人时（工程师+分析师）的人力成本。按保守估计，这相当于每周节省了数百美元。更重要的是，处理速度提升了一个数量级，系统可靠性大幅提高，为业务提供了实时或准实时的数据洞察能力，这个业务价值远超增加的那点API费用。

6. 踩坑实录与核心经验

坑一：Token消耗与上下文长度的陷阱 最初，我们试图将24页的所有文本（约5万字）一次性塞给Gemini。这导致了极高的Token消耗（>150K）和缓慢的响应速度。 教训 ：一定要做“上下文修剪”。只提供完成任务所必需的最小上下文。使用摘要、关键词提取等技术，将长文本压缩后再送入LLM。

坑二：LLM输出的不稳定性 即使温度设为0，LLM的输出格式偶尔也会偏离要求，比如JSON缺少引号，或字段名微变。 解决方案 ：

1. 结构化输出强制 ：使用Pydantic等库，在代码层定义严格的响应模型，并在提示词中明确要求。OpenRouter也支持一些模型的“JSON模式”调用。
2. 后处理与重试 ：在解析LLM响应时，用 try-except 包裹。如果JSON解析失败，可以尝试用简单的字符串修复（如补全引号），或者将错误输出连同原提示词再次发送给LLM，要求其修正。
3. Few-shot示例 ：在提示词中提供1-2个完美的输入输出示例，这是稳定输出格式最有效的方法之一。

坑三：混合策略的复杂性管理 系统有多个分支（规则、传统OCR、LLM），管理起来复杂。 经验 ：

• 建立清晰的决策树 ：用配置化的方式定义页面分类规则和处理路由，而不是硬编码在逻辑中。
• 完善的日志记录 ：记录每一页走了哪条处理路径、消耗了多少Token、耗时多久、结果置信度。这些日志是后续优化和排查问题的黄金数据。
• 设置降级开关 ：当LLM API持续失败或成本超标时，能一键切换回“保守模式”（仅使用规则和传统OCR），保证服务不中断。

坑四：成本监控与预警 LLM API成本是变量，必须监控。 我们的做法 ：

1. 在OpenRouter仪表板设置每日/每周预算告警。
2. 在应用层，为每个处理任务记录详细的Token使用情况，并关联到具体的报告类型和供应商。
3. 定期（每周）分析成本报告，识别是否有异常消耗（例如，某个供应商的PDF格式突变导致所有页面都走了昂贵的LLM路径），从而及时调整预处理策略或提示词。

一个关键的实操心得 ： 不要追求100%的LLM解析率 。对于格式极其规整、稳定的数据，传统方法（如正则表达式、专用PDF表格库）更快、更准、成本为零。将LLM视为一个“智能补偿器”，用它来处理那20%的复杂、多变、非结构化的部分，解决80%的难题。这种“混合智能”的架构，才是当前性价比最高的工程实践。