Hotdry.
归档
ai-systems

构建可复现的源归因评估流水线

基于 LangExtract 库，从数据标注、多模型并行推理到指标计算与可视化，构建一个可复现的源归因评估流水线，确保 LLM 提取信息的可追溯性与可靠性。

在大型语言模型（LLM）应用于信息提取的实践中，评估其输出质量至关重要，而 “源归因”（Source Grounding）—— 即模型提取的每一项信息都能追溯到源文本中的确切位置 —— 是衡量可靠性的核心维度。一个粗糙的评估脚本或许能给出表面分数，但难以支撑持续的模型对比、 prompt 调优与错误根因分析。本文旨在阐述如何基于 Google 开源的 langextract Python 库，构建一个工程化、可复现的源归因评估流水线，覆盖从数据准备、并行推理到指标计算与可视化的完整闭环。

评估流水线的三层架构

一个健壮的评估系统可抽象为三层：数据层、执行层与分析层。

数据层：任务定义与金标准标注

评估始于清晰、一致的任务定义。在 LangExtract 中，任务由 prompt_description（自然语言指令）和 examples（少量示例）共同定义。为确保评估的可复现性，这两者必须作为代码或配置文件的一部分进行版本控制。

更重要的是 “金标准”（Ground Truth）数据集的构建。对于源归因评估，金标准不仅需要包含期望提取的实体或关系列表，还必须为每一项提供其在源文本中的精确字符偏移量（start_char， end_char）。这通常是一个人工标注过程，可借助标注工具完成，最终输出格式应与 LangExtract 的 Extraction 数据类兼容。一个建议的标注 JSONL 格式如下：

{
  "text_id": "doc_001",
  "text": "...原文内容...",
  "ground_truth_extractions": [
    {
      "extraction_class": "character",
      "extraction_text": "ROMEO",
      "start_char": 0,
      "end_char": 5,
      "attributes": {"emotional_state": "wonder"}
    }
  ]
}

将任务定义与金标准数据集分离，允许我们独立地评估同一数据集上不同 prompt 或不同模型的表现。

执行层：多模型并行推理流水线

LangExtract 的核心函数 lx.extract() 是执行层的发动机。为了进行系统评估，我们需要将其封装为一个可配置的流水线，能够依次或并行地在多个模型上运行相同的任务和数据集。

关键的设计参数包括：

  1. 模型列表：指定要评估的模型 ID（如 ["gemini-2.5-flash", "gpt-4o", "gemma2:2b"]）。对于本地模型（通过 Ollama），需确保相应的模型服务已启动。
  2. 并行化参数：利用 max_workers 控制并发度，以加速对大规模数据集的评估。注意，不同云 API 可能有速率限制，需合理设置。
  3. 提取策略参数：extraction_passes（多轮提取以提高召回率）和 max_char_buffer（上下文窗口大小）等参数会显著影响结果，必须在评估中固定并记录。
  4. 环境与认证：API 密钥或服务账户凭证应通过环境变量或安全的 Secret 管理工具注入，避免硬编码。

一个简化的流水线执行伪代码如下：

import langextract as lx
from concurrent.futures import ThreadPoolExecutor
import json

def evaluate_model_on_dataset(model_id, dataset, prompt_desc, examples, params):
    """在单个模型上运行评估"""
    results = []
    for item in dataset:
        result = lx.extract(
            text_or_documents=item["text"],
            prompt_description=prompt_desc,
            examples=examples,
            model_id=model_id,
            **params  # 固定化的提取参数
        )
        # 将结果转换为与金标准可比的形式
        serializable_result = {"text_id": item["text_id"], "extractions": result.to_dict()}
        results.append(serializable_result)
    return {model_id: results}

# 配置
models_to_evaluate = ["gemini-2.5-flash", "gpt-4o"]
fixed_params = {"extraction_passes": 2, "max_workers": 4, "max_char_buffer": 1000}

evaluation_results = {}
with ThreadPoolExecutor(max_workers=len(models_to_evaluate)) as executor:
    futures = []
    for model in models_to_evaluate:
        future = executor.submit(evaluate_model_on_dataset, model, gold_standard_dataset, prompt_desc, examples, fixed_params)
        futures.append((model, future))
    
    for model, future in futures:
        evaluation_results.update(future.result())

# 将原始结果持久化
with open("evaluation_raw_results.json", "w") as f:
    json.dump(evaluation_results, f, indent=2)

此步骤的输出是每个模型在每份文档上的原始提取结果（包含源归因信息），保存为 JSON 文件以供后续分析。

分析层：指标计算与可视化审查

分析层的任务是将模型的原始输出与金标准进行比较，计算量化指标，并提供工具进行人工深度审查。

1. 归因准确性指标计算

对于源归因，经典的精确匹配（Exact Match）过于严苛。更实用的指标是基于字符偏移量的重叠度度量，例如：

  • 归因精度（Grounding Precision）：模型提取的片段中，其字符跨度与金标准中任何一项的跨度重叠度（如 IoU）超过阈值（如 0.8）的比例。
  • 归因召回率（Grounding Recall）：金标准项中，被模型提取且跨度重叠度超过阈值的比例。

计算这些指标需要解析 LangExtract 输出结果中的 extraction_text 及其在源文本中的隐含或显式位置信息。虽然 langextract 目前未直接返回字符偏移量，但其 “精确源归因” 的设计目标意味着在可视化或内部表示中必然存在此信息。我们可以通过解析生成的 HTML 或扩展库的功能来获取偏移量。一个可行的计算函数框架如下：

def calculate_grounding_metrics(predicted_extractions, ground_truth_extractions, iou_threshold=0.8):
    """计算归因级别的精度、召回率和 F1。
    假设 predicted_extractions 和 ground_truth_extractions 都已包含字符偏移量。
    """
    tp, fp, fn = 0, 0, 0
    for pred in predicted_extractions:
        matched = False
        for gt in ground_truth_extractions:
            iou = compute_iou(pred["span"], gt["span"]) # 计算跨度交并比
            if iou >= iou_threshold and pred["class"] == gt["class"]: # 类别也需匹配
                matched = True
                break
        if matched:
            tp += 1
        else:
            fp += 1
    fn = len(ground_truth_extractions) - tp
    precision = tp / (tp + fp) if (tp + fp) > 0 else 0
    recall = tp / (tp + fn) if (tp + fn) > 0 else 0
    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0
    return {"precision": precision, "recall": recall, "f1": f1, "tp": tp, "fp": fp, "fn": fn}

2. 可视化审查与错误分析

指标仅能提供宏观视图，深度的错误分析需要回到具体文本上下文中。这正是 LangExtract 内置可视化功能的用武之地。我们可以：

  • 为每个模型生成独立的 visualization.html 文件，将模型提取项高亮显示在原文上。
  • 将金标准标注也以不同颜色高亮，并排显示，便于人工快速比对模型输出与标准的差异。
  • 聚焦于指标表现差的样本，利用可视化定位归因错误的具体模式：是模型提取了错误文本，还是定位的跨度略有偏差？

通过结合自动化指标和交互式可视化，评估者可以高效地识别模型在特定类型文本或实体上的弱点，从而迭代改进 prompt 设计或考虑模型融合策略。

可复现性的工程保障

构建流水线只是第一步，确保其可复现性需要额外的工程实践：

  1. 容器化：使用 Docker 将评估环境（Python 版本、依赖包、本地模型运行时）固化，消除 “在我机器上能运行” 的问题。
  2. 配置即代码：所有参数（模型列表、提取参数、评估阈值）应置于配置文件（如 YAML）中，与代码一同版本化。
  3. 流水线编排：对于复杂的多步骤评估（数据预处理→模型 A 评估→模型 B 评估→指标计算→报告生成），可使用轻量级流水线工具（如 dvc 或 prefect）进行编排，确保每一步的输入输出清晰且可缓存。
  4. 结果版本化：每次评估运行的原始结果、计算出的指标和生成的报告都应打上唯一标识（如 git commit hash 或时间戳），并与对应的代码和配置版本关联存储。

局限与展望

当前基于 LangExtract 构建的评估流水线仍面临一些挑战：首先，评估的绝对可靠性受限于金标准标注的质量与一致性，标注过程本身可能引入偏差。其次，对于高度抽象或需要推理的提取任务，简单的字符跨度重叠可能不足以全面评估归因质量。未来，可以探索引入更细粒度的评估维度，如归因置信度、对上下文依赖的合理性等。

结语

评估不是一次性的验收，而是驱动 LLM 应用迭代优化的核心反馈循环。本文勾勒的评估流水线蓝图，将 LangExtract 从强大的提取工具，升级为可度量、可分析、可复现的评估平台。通过将数据、执行与分析三层解耦，并强调工程化实践，团队可以系统化地对比不同模型与 prompt 策略在源归因任务上的真实表现，从而做出更可靠的技术决策，最终构建出值得信赖的信息提取系统。

资料来源

  1. LangExtract 官方 GitHub 仓库：https://github.com/google/langextract
  2. 本文中关于评估指标与流水线设计的讨论，基于通用的机器学习评估原则与软件工程最佳实践。
查看归档