GoLLIE：基于Code Llama的零样本信息抽取模型实战指南

1. 项目概述：当大语言模型学会“照章办事”

在信息抽取这个领域里，我们常常面临一个困境：模型要么是“死记硬背”型的专家，只能在训练过的、固定模式的任务上表现良好，一旦遇到新的、从未见过的实体类型或关系定义，就立刻“傻眼”；要么是依赖“常识”的通用模型，虽然能理解新概念，但抽取结果往往随心所欲，难以严格遵循我们精心设计的、包含各种约束和细节的标注规范。这就像你请了一位经验丰富的助手，但他要么只会做你教过的那几件事，要么就完全按自己的理解自由发挥，总是不太“听话”。

GoLLIE的出现，正是为了解决这个核心痛点。它的全称是Guideline-following Large Language Model for Information Extraction，直译过来就是“遵循指南的大语言模型用于信息抽取”。这个名字精准地概括了它的核心能力：它被专门训练来理解和遵循人类编写的、详细的标注指南（Guidelines）。这意味着，你可以像给实习生下发一份操作手册一样，为GoLLIE定义一套全新的、复杂的抽取规则（比如定义“航天发射任务”必须包含“发射日期”、“运载火箭”、“宇航员名单”等字段，并且每个字段都有具体的格式和取值说明），而GoLLIE能够像一位严谨的资深员工一样，严格地按照这份手册去分析文本，并输出结构化的结果。

这个项目基于Meta开源的Code Llama模型进行微调，目前提供了7B、13B和34B三种参数规模的版本。它的最大亮点在于零样本（Zero-Shot）信息抽取能力。你不需要用成千上万条标注数据去重新训练它，只需要在推理时，通过一种巧妙的结构化提示（Prompt）方式，将你的标注规范“教”给它，它就能立刻上岗工作。这对于快速构建领域特定的信息抽取系统、处理标注数据稀缺的长尾任务，具有革命性的意义。

2. 核心设计思路：为什么“照章办事”如此困难又如此重要？

要理解GoLLIE的价值，我们需要先拆解一下传统信息抽取方法，特别是基于大语言模型（LLM）的方法，在遵循复杂指南时面临的挑战。

2.1 传统方法的局限：从“死记硬背”到“自由发挥”

在GoLLIE之前，主流的信息抽取路径大致有两条：

1. 监督学习模型：如经典的BERT-CRF、Span-based模型等。这类模型是典型的“专家型”选手。它们在一个固定的、预定义的标签集（如人名、地名、组织机构名）上进行训练，性能可以达到很高的水平。但它们的“知识”完全固化在模型参数中。如果你想让它识别一种新的实体类型（比如“电影中的超能力”），就必须重新收集数据、重新标注、重新训练模型。这个过程成本高昂、周期长，缺乏灵活性。

2. 基于提示（Prompting）的通用LLM：随着ChatGPT等模型的兴起，人们开始尝试直接用自然语言指令让LLM进行抽取，例如：“请从下面这段话中找出所有公司的名字”。这种方法灵活度极高，理论上可以处理任何新定义的任务。但问题也随之而来：

   • 不一致性：同样的指令，模型在不同时间、不同上下文下可能给出格式完全不同的答案（有时是列表，有时是JSON，有时是一段话）。
   • 忽视细节：复杂的指南往往包含许多约束条件（如“日期必须格式化为YYYY-MM-DD”、“如果未提及则留空”）。通用LLM很容易忽略这些细节，或者根据自己的“常识”进行脑补，而不是严格依据文本。
   • 幻觉（Hallucination）：模型可能会输出文本中根本不存在的“事实”。

问题的根源在于，通用LLM的训练目标是“续写”出最符合统计规律的下一个词，而不是“精确执行”一个结构化的、带有约束的指令。它更像一个富有创造力的作家，而不是一个严谨的数据录入员。

2.2 GoLLIE的破局之道：将指南“编译”进模型的理解中

GoLLIE的设计者洞察到了一个关键点：标注指南本身是一种高度结构化的“代码”或“规范”。那么，为什么不利用擅长理解结构化语言的模型来学习它呢？

这就是他们选择Code Llama作为基座模型的原因。Code Llama在大量代码数据上进行了预训练，对类、函数、数据结构、文档字符串（docstrings）等编程概念有着深刻的理解。GoLLIE的微调过程，本质上就是教会这个“程序员”模型，如何将一段用自然语言和类定义（Class Definition）编写的“业务需求文档”（即标注指南），转化为从文本中“运行”并“输出”结构化数据的“程序”。

GoLLIE的核心创新在于其“提示模板”。它没有使用简单的自然语言指令，而是设计了一套基于Pythondataclass的模板。这套模板做了以下几件关键事：

1. 结构化定义：每个需要抽取的实体或事件，都被定义为一个Python类。类的属性（mention,date,crew等）对应了需要抽取的字段。
2. 指南即文档：详细的标注规则和示例，被直接写入类的文档字符串（""" ... """）和每个属性的注释中。这利用了代码模型对文档字符串的天然关注。
3. 上下文示例：在提示中，除了目标文本和定义，还会包含少量（通常是2-4个）其他任务的输入输出示例。这些示例展示了模型应该如何“思考”和“格式化”输出，起到了“少样本学习”的作用。
4. 强制结构化输出：提示的结尾固定为result = [，模型的任务就是续写一个符合之前定义的、合法的Python对象列表。这种格式强制模型输出结构化的、可解析的结果，极大减少了不一致性。

通过在海量、多样的信息抽取任务数据上，以上述格式进行指令微调，GoLLIE内化了一种能力：将“类定义+文档字符串”这种形式的指南，映射到“从文本中实例化对象”这个动作上。它学会了严格遵循属性类型（字符串、列表等）、尊重文档中的约束条件，并只基于给定文本进行推理。

注意：这种方法的有效性强烈依赖于基座模型的结构化理解能力。这也是为什么选择Code Llama而非纯文本LLM的原因。Code Llama对语法、数据结构有更强的意识，能更好地保证输出格式的正确性。

3. 实操详解：手把手玩转GoLLIE

理解了原理，我们来看看如何实际使用GoLLIE。项目提供了Hugging Face模型和详细的Jupyter Notebook，这里我将结合官方示例和我的实操经验，为你拆解每一步。

3.1 环境搭建与模型加载

首先，你需要一个支持CUDA的GPU环境。GoLLIE的模型不小，7B版本至少需要16GB GPU内存（使用量化技术可降低），34B版本则需要更大的显存。

安装依赖： 官方依赖列表比较全，但根据我的经验，可以按以下顺序安装，避免版本冲突：

# 1. 安装PyTorch (请根据你的CUDA版本去官网获取对应命令) # 例如，对于CUDA 11.8： pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 2. 安装Transformers, PEFT, Bitsandbytes (用于量化加载) pip install transformers>=4.33.1 peft>=0.4.0 bitsandbytes>=0.40.0 # 3. 安装Flash Attention 2 (大幅加速注意力计算，强烈建议安装) # 这一步可能因系统环境而异，如果安装失败，可以暂时跳过，但推理速度会慢很多。 pip install flash-attn --no-build-isolation # 4. 安装其他工具库 pip install numpy jinja2 tqdm rich psutil datasets

加载模型： GoLLIE模型已经集成到Hugging Face的transformers库中，加载非常方便。这里以7B模型为例，展示如何使用4-bit量化来在消费级显卡（如24GB的RTX 4090）上运行34B模型。

from transformers import AutoTokenizer, AutoModelForCausalLM import torch model_id = "HiTZ/GoLLIE-7B" # 或 "HiTZ/GoLLIE-34B" # 加载tokenizer tokenizer = AutoTokenizer.from_pretrained(model_id) tokenizer.padding_side = "left" # 对于生成任务，通常左侧填充 tokenizer.pad_token = tokenizer.eos_token # 使用EOS token作为填充token # 使用4-bit量化加载模型，极大减少显存占用 model = AutoModelForCausalLM.from_pretrained( model_id, torch_dtype=torch.float16, # 使用半精度浮点数 device_map="auto", # 自动将模型层分布到可用的GPU/CPU上 load_in_4bit=True, # 启用4-bit量化 bnb_4bit_compute_dtype=torch.float16, bnb_4bit_quant_type="nf4", # 使用NF4量化类型，效果更好 ) model.eval() # 设置为评估模式

实操心得：load_in_4bit=True是让大模型在有限显存上运行的关键。实测中，34B模型量化后大约需要20GB显存。如果加载失败，检查bitsandbytes库是否正确安装，并确保你的PyTorch是CUDA版本。另外，首次加载模型会下载约20GB（7B）或70GB（34B）的数据，请确保网络通畅和磁盘空间充足。

3.2 定义你的第一个抽取任务

让我们复现论文中的经典例子：从航天文本中抽取“发射器”和“任务”。关键在于构建那个结构化的提示。

from dataclasses import dataclass from typing import List # 1. 定义你的数据类（即标注规范） @dataclass class Launcher: """Refers to a vehicle designed primarily to transport payloads from the Earth's surface to space. Launchers can carry various payloads, including satellites, crewed spacecraft, and cargo, into various orbits or even beyond Earth's orbit. They are usually multi-stage vehicles that use rocket engines for propulsion.""" mention: str """The name of the launcher vehicle. Such as: "Saturn V", "Atlas V", "Soyuz", "Ariane 5" """ space_company: str # The company that operates the launcher. crew: List[str] # Names of the crew members boarding the Launcher. @dataclass class Mission: """Any planned or accomplished journey beyond Earth's atmosphere with specific objectives, either crewed or uncrewed.""" mention: str """The name of the mission. Such as: "Apollo 11", "Artemis", "Mercury" """ date: str # The start date of the mission departure: str # The place from which the vehicle will be launched. destination: str # The place or planet to which the launcher will be sent. # 2. 准备提示模板 def build_prompt(task_definition: str, text: str) -> str: prompt_template = """# Task: Extract information based on the following definitions. {task_definition} # This is the text to analyze: text = \"\"\"{input_text}\"\"\" # The annotation instances that take place in the text above are listed here: result = [""" return prompt_template.format(task_definition=task_definition, input_text=text) # 3. 构建任务定义字符串（这里简化了，实际应包括更多示例） task_def_code = "\n".join([Launcher.__doc__, str(Launcher), Mission.__doc__, str(Mission)]) # 注意：实际应用中，需要更优雅地生成类定义的字符串表示，包括属性注释。 # 4. 待分析的文本 input_text = ( "The Ares 3 mission to Mars is scheduled for 2032. The Starship rocket built by SpaceX will take off from Boca Chica, " "carrying the astronauts Max Rutherford, Elena Soto, and Jake Martinez." ) # 5. 构建完整提示 prompt = build_prompt(task_def_code, input_text) print("=== 完整提示 ===") print(prompt) print("="*50)

运行上面的代码，你会得到一个结构化的提示，它清晰地定义了任务，并给出了待分析的文本。模型的任务就是补全result = [之后的内容。

3.3 执行推理与解析结果

有了提示，接下来就是让模型生成。

# 编码提示词 inputs = tokenizer(prompt, return_tensors="pt", padding=True, truncation=True).to(model.device) # 生成参数设置 generation_args = { "max_new_tokens": 256, # 生成的最大新token数 "do_sample": False, # 为了确定性结果，使用贪婪解码 "temperature": 0.0, "top_p": 1.0, "eos_token_id": tokenizer.eos_token_id, "pad_token_id": tokenizer.pad_token_id, } # 执行生成 with torch.no_grad(): outputs = model.generate(**inputs, **generation_args) # 解码生成结果 # 只取生成的部分（跳过输入提示） generated_sequence = outputs[0][inputs['input_ids'].shape[1]:] generated_text = tokenizer.decode(generated_sequence, skip_special_tokens=True) print("=== 模型生成结果 ===") print(generated_text)

理想情况下，模型会输出类似这样的内容：

Mission(mention='Ares 3', date='2032', departure='Boca Chica', destination='Mars'), Launcher(mention='Starship', space_company='SpaceX', crew=['Max Rutherford', 'Elena Soto', 'Jake Martinez']) ]

解析结果： 模型输出的是Python代码片段。为了安全地将字符串转换为对象，我们可以使用ast.literal_eval或更安全地，编写一个简单的解析器。

import ast import re def parse_gollie_output(output_text: str): """ 解析GoLLIE的输出字符串，尝试将其转换为对象列表。 这是一个简化的解析器，实际应用可能需要更健壮的处理。 """ # 找到 `result = [` 之后的部分，并补全为一个完整的列表表达式 # 假设输出是干净的，以 `]` 结尾 list_str = "[{" + output_text.replace("),", "},").replace("(", "{").replace(")", "}") + "]" # 将类名作为键，例如 Mission(...) -> {"Mission": {...}} # 这里需要更精细的解析来匹配属性名，以下仅为示意 pattern = r'(\w+)\(([^)]+)\)' matches = re.findall(pattern, output_text) results = [] for cls_name, args_str in matches: arg_dict = {} for part in args_str.split(','): if '=' in part: key, val = part.split('=', 1) key = key.strip() val = val.strip().strip("'\"") # 去除引号 # 处理列表类型的值 if val.startswith('['): val = ast.literal_eval(val) arg_dict[key] = val results.append({"type": cls_name, **arg_dict}) return results parsed_results = parse_gollie_output(generated_text.strip()) print("=== 解析后的结构化结果 ===") import pprint pprint.pprint(parsed_results)

重要提示：生产环境中，解析模型输出需要极其谨慎。建议：

1. 使用ast.literal_eval配合安全的环境。
2. 或者，利用Python的dataclasses和eval（极度危险，不推荐）或type动态创建类来实例化。最安全的方式是不执行模型生成的代码，而是将其视为一种严格的序列化格式，用自定义解析器提取键值对。
3. 官方Notebook中可能提供了更完善的解析工具，建议优先参考。

3.4 进阶技巧：使用少样本示例提升效果

零样本（Zero-Shot）虽然强大，但在处理极其复杂或模糊的指南时，效果可能不稳定。GoLLIE支持在提示中加入少量示例（Few-Shot），能显著提升表现。

关键点在于如何构建示例：示例必须与主任务遵循完全相同的格式。通常，你需要为模型提供2-4个其他任务（或同一任务不同实例）的完整输入输出对。

# 假设我们有一个“电影信息抽取”的少样本示例 few_shot_examples = """ # Example 1: # Entity definitions for Movie @dataclass class Movie: """A cinematic film.""" title: str director: str release_year: int text = \"\"\"In 1994, Quentin Tarantino directed the iconic film Pulp Fiction.\"\"\" result = [Movie(title='Pulp Fiction', director='Quentin Tarantino', release_year=1994)] # Example 2: # (另一个不同领域的示例，比如书籍) @dataclass class Book: """A published work of literature.""" title: str author: str genre: str text = \"\"\"J.K. Rowling's fantasy novel Harry Potter and the Philosopher's Stone was published in 1997.\"\"\" result = [Book(title='Harry Potter and the Philosopher\'s Stone', author='J.K. Rowling', genre='fantasy')] """ # 然后将这些示例插入到提示模板中，放在任务定义和待分析文本之间。 def build_few_shot_prompt(task_def, examples, input_text): prompt = f"""# Task: Extract information based on the following definitions. {task_def} # Below are some examples of how to perform similar tasks: {examples} # Now, analyze the following text: text = \"\"\"{input_text}\"\"\" result = [""" return prompt

通过提供示例，你实际上是在教模型：“看，当你看到这种格式的定义和文本时，应该这样格式化和输出结果。”这对于对齐模型的输出格式和理解复杂约束至关重要。

4. 训练你自己的GoLLIE：从数据到模型

如果你有特定领域的大量标注数据，并且希望获得比零样本/少样本更好的性能，可以尝试微调你自己的GoLLIE模型。这个过程需要较强的计算资源和数据准备能力。

4.1 数据准备：构建GoLLIE格式数据集

GoLLIE的训练数据需要被转换成它特有的“代码提示”格式。项目提供了数据生成脚本，但你需要准备好原始数据集。

核心步骤：

1. 获取数据集：项目支持多种公开数据集（如CoNLL-2003, OntoNotes, TACRED等）。你需要根据configs/data_configs/下的配置文件，下载或指定这些数据集的路径。注意，像ACE05这样的数据集需要LICENSE。
2. 理解数据配置：每个JSON配置文件定义了如何将原始标注转换为GoLLIE格式。例如，conll03_config.json定义了如何将“PER”, “ORG”等实体类型，包装成带有说明的dataclass。
3. 运行生成脚本：

   python -m src.generate_data \ --configs configs/data_configs/conll03_config.json \ --output ./my_processed_data \ --include_examples

   --include_examples参数会在每个训练样本中包含少样本示例，这对学习遵循指南至关重要。

数据格式解析： 生成的数据集每条样本可能长这样（简化）：

{ "input": "# Task: Extract Person, Organization, Location entities.\n@dataclass\nclass Person:\n \"\"\"A human being.\"\"\"\n mention: str\n\n... (其他类定义) ...\n\n# Examples:\ntext = \"...\"\nresult = [...]\n\n# Text to analyze:\ntext = \"Apple is looking at buying U.K. startup for $1 billion.\"\nresult = [", "output": "Organization(mention='Apple'), Location(mention='U.K.')]" }

模型的任务就是学习从input到output的映射。

4.2 模型训练配置与执行

GoLLIE使用基于PEFT（Parameter-Efficient Fine-Tuning）的QLoRA技术进行微调，这可以在单张消费级显卡上微调大型模型。

1. 配置文件：复制一份configs/model_configs/GoLLIE-7B_CodeLLaMA.yaml作为起点。
2. 关键配置项：

   model_name_or_path: "codellama/CodeLlama-7b-hf" # 基座模型 data_path: "./data/processed_w_examples" # 处理后的数据路径 output_dir: "./gollie-finetuned-7b" # 输出目录 # QLoRA 配置 load_in_4bit: true bnb_4bit_compute_dtype: "float16" bnb_4bit_quant_type: "nf4" # 训练参数 num_train_epochs: 3 per_device_train_batch_size: 4 # 根据GPU内存调整 gradient_accumulation_steps: 4 learning_rate: 2e-4 lr_scheduler_type: "cosine" # 序列长度需要足够长以容纳复杂的提示 max_source_length: 2048 max_target_length: 512

3. 启动训练：

   python -m src.run configs/my_gollie_config.yaml

训练心得与避坑指南：

• 显存不足：如果遇到CUDA out of memory，首先降低per_device_train_batch_size，增加gradient_accumulation_steps以保持总batch size。其次，可以尝试gradient_checkpointing: true。
• 序列长度：max_source_length必须设置得足够大，以容纳最长的提示（包括所有类定义和示例）。建议先分析数据集中提示的长度分布。
• 数据质量：确保生成的数据集中，input和output的格式完全正确。一个常见的错误是输出格式与提示中的类定义不匹配（如属性名拼写错误）。
• 评估：项目也提供了评估脚本。在训练过程中或训练后，在保留的验证集上运行评估，查看F1分数等指标，以判断模型是否学到了遵循指南的能力，而不是简单地记忆训练数据中的实体。

5. 常见问题、排查技巧与性能优化

在实际使用和复现GoLLIE的过程中，你可能会遇到以下问题。这里我整理了一份排查清单和优化建议。

5.1 模型推理常见问题

问题1：模型输出格式错误，无法解析。

• 现象：生成的文本不是有效的Pythondataclass实例化代码，或者缺少括号、逗号。
• 排查：
  1. 检查提示格式：确保你的提示模板与训练数据格式完全一致，特别是result = [这一行，空格和换行符都不要错。
  2. 检查任务定义：确保你的dataclass定义语法正确，属性名是有效的Python标识符。
  3. 使用少样本示例：在提示中加入2-3个格式完美的示例，可以极大地引导模型输出正确的格式。
  4. 调整生成参数：尝试将do_sample设为False（贪婪解码），temperature设为0，以获得更确定性的输出。如果输出被截断，增加max_new_tokens。
• 根本原因：模型在零样本情况下对输出格式的把握不够精确。微调过的GoLLIE在这方面已经很强，但极端复杂的指南仍可能出错。

问题2：模型“幻觉”（Hallucination），抽取了文本中没有的信息。

• 现象：输出结果中的某个属性值在原文中找不到对应描述。
• 排查：
  1. 审视指南的模糊性：检查你的标注指南（docstring）是否足够清晰。例如，“日期”属性是否明确要求必须是文本中明确提及的？模型可能会根据常识推断日期。
  2. 提供反例：在少样本示例中，可以包含一个属性值为None或空字符串""的例子，并说明“当文本未提及时应留空”。
  3. 后处理校验：实现一个简单的后处理步骤，将模型输出的每个属性值回标到原文中，检查是否存在原文片段与之匹配。如果没有，则将该属性置为None或发出警告。
• 根本原因：大语言模型固有的补全倾向。即使被训练为遵循指南，在信息模糊时仍可能依赖内部知识进行“合理”猜测。

问题3：抽取不全，漏掉了明显的实体或关系。

• 现象：文本中明显存在符合定义的信息，但模型没有输出。
• 排查：
  1. 检查定义覆盖：确认你定义的类（如Launcher,Mission）是否涵盖了文本中所有应被抽取的信息类型。
  2. 检查属性约束：属性注释中的示例（Such as: ...）是否具有代表性？如果示例太窄，模型可能无法泛化。
  3. 文本长度：输入文本是否过长，超过了模型的上下文窗口？Code Llama的上下文长度是4096或16384（取决于版本），提示本身会占用大量token，留给文本的空间可能不足。考虑对长文档进行分块处理。
  4. 尝试少样本：提供包含类似实体的示例。

5.2 性能与效率优化

1. 推理速度慢

• 启用Flash Attention 2：如安装指南所述，正确安装Flash Attention 2可以带来数倍的推理速度提升。确保你的PyTorch版本和CUDA环境与之兼容。
• 使用量化：如前所述，使用load_in_4bit=True加载模型不仅能降低显存占用，在某些情况下也能轻微加速。
• 批处理（Batching）：如果需要处理大量文本，尽量将多个提示组成一个批次输入模型。注意需要统一填充（padding）。

  # 假设prompts是一个提示字符串列表 inputs = tokenizer(prompts, return_tensors=“pt”, padding=True, truncation=True, max_length=2048).to(model.device) outputs = model.generate(**inputs, **generation_args) # 然后分别解码每个结果

2. 显存不足（OOM）

• 量化是首选：4-bit量化是运行大模型的利器。
• 启用CPU Offload：对于非常大的模型（如34B），即使量化后显存仍不足，可以尝试使用accelerate库的device_map=“sequential”或更精细的device_map设置，将部分模型层卸载到CPU内存，但会显著降低速度。
• 减少批次大小和序列长度：在训练和推理时，这都是最直接的显存控制手段。

5.3 领域适配建议

GoLLIE的零样本能力很强，但要让它在你的特定领域达到最佳效果，可能需要一些“调教”。

• 编写高质量的指南（Docstring）：这是最重要的环节。指南应：
  • 清晰无歧义：用精确的语言描述实体或事件的边界。
  • 提供典型示例：在属性注释中使用Such as: “Example1”, “Example2”。这比单纯的文字描述有效得多。
  • 说明排除情况：如果可能，说明什么“不属于”这个类别。
• 构建有效的少样本示例：
  • 多样性：示例应覆盖不同类型的文本和不同的属性组合（包括空值）。
  • 相关性：示例任务最好与你的目标任务在结构或领域上相似。
  • 格式完美：确保示例的输出格式与你期望的完全一致。
• 后处理管道：不要完全信任模型的原始输出。建立一个后处理管道，用于：
  • 格式校验与修复：自动修正常见的格式小错误（如缺失的引号、尾随逗号）。
  • 值标准化：将模型抽取的日期、金额等字符串转换为标准格式。
  • 去重与融合：对于可能被重复抽取的同一实体，进行去重和证据融合。

GoLLIE代表了一种将大语言模型与结构化约束相结合的新范式。它没有试图让模型“理解一切”，而是聪明地利用模型的结构化语言能力，让它成为一个可靠的“规则执行者”。对于需要快速构建可定制、高精度信息抽取系统的开发者来说，它提供了一个极具吸引力的新工具。从简单的命名实体识别到复杂的事件图谱构建，你只需要用Python类定义和自然语言描述出你的“规则手册”，剩下的，就可以交给这个学会了“照章办事”的AI助手了。