trex

图1：Automorphic AI 团队 GitHub 头像

一、痛点切入：LLM 输出「自由过头」的问题

当你在用 GPT-4 或 Claude 处理结构化任务——比如从一段客服对话中提取用户信息、生成符合数据库 schema 的 JSON——你很可能遇到过这样的崩溃：模型输出的 JSON 格式对不上、缺少字段、多了个多余的逗号，甚至有时候直接「thought」了一整段再给你结果。

这不是模型的 bug，而是概率模型的本质问题：LLM 是「文字生成器」，它擅长流畅表达，但不擅长精确遵循格式指令。prompt 里写一百遍「输出严格符合 JSON Schema」，在 few-shot 示例加持下能改善一些，但依然无法保证 100% 有效。

automorphic-ai/trex 解决的就是这个问题——它是一个 Python 库，让 LLM 100% 产生格式正确的结构化输出，无论是 JSON、符合上下文无关文法（CFG）的字符串，还是正则表达式约束的文本。

二、项目背景：Automorphic AI 的开源处女作

Trex（Transformer Regular EXpressions，即 Transformer 正则表达式）由初创公司 Automorphic AI 于 2023 年 7 月开源。该公司专注于 LLM 输出控制技术，核心目标是让大语言模型从「随心所欲的文字生成器」变成「可靠的结构化数据处理器」。

Trex 是该公司在 GitHub 上的首个公开仓库，虽然代码仓库规模不大（仅 3 个 Python 源文件），但它的技术方案在 LLM 工程化领域具有相当的参考价值。截至 2026 年 7 月，项目已获得 251 颗 GitHub Stars，在「LLM 输出结构化」这一细分赛道上积累了一定的社区关注度。

项目的两位核心作者 Mahesh Natamai 和 Govind Gnanakumar 同时运营着 Automorphic AI 平台（automorphic.ai），提供云端 API 服务，Trex 是其开源客户端库。

三、核心原理：Lark CFG + JSON Schema 双引擎

Trex 的技术内核可以理解为一个格式约束编译器。当你传入一个 prompt 和期望的输出格式时，Trex 并不直接调用 LLM——它先在服务端将格式约束编译成 Lark 上下文无关文法（CFG），然后通过特殊的 prompt engineering 让 LLM 在该文法的约束下生成内容。

3.1 三种结构化模式

模式一：JSON Schema（最常用）

最直接的使用方式是传入一个标准 JSON Schema，Trex 将其转换为 Lark 文法，引导模型生成严格符合 schema 的 JSON：

import trex

tx = trex.Trex('<YOUR_AUTOMORPHIC_API_KEY>')
json_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "pets": {
            "type": "array",
            "items": [{"type": "object", "properties": {
                "name": {"type": "string"},
                "species": {"type": "string"}
            }}]
        }
    }
}
prompt = "生成一个30岁的人，名字叫dave，有一只叫trex的狗。"
result = tx.generate_json(prompt, json_schema=json_schema)
print(result.response)  # 100% 符合 schema

模式二：自定义 CFG 文法

如果你需要更精确的格式控制，可以直接写 Lark DSL 文法字符串。Lark 是 Python 生态中成熟的 CFG 解析库，Trex 直接复用其语法。对于一段正则约束格式的文本：

cfg_grammar = r"""
    ?start: object
    object : "{" [pair ("," pair)*] "}"
    pair   : string ":" value
    value  : string | number | "true" | "false" | "null"
    string : ESCAPED_STRING
    %import common.ESCAPED_STRING
    %import common.SIGNED_NUMBER
    %import common.WS
    %ignore WS
"""
result = tx.generate_cfg(prompt, cfg=cfg_grammar)

模式三：正则表达式约束

对于更细粒度的文本模式（如手机号、邮箱、特定格式的 ID），Trex 支持通过正则表达式约束输出内容，适用于数据抽取、实体识别等 ETL 场景。

3.2 背后的推理机制

Trex 并非简单地在 prompt 末尾追加格式要求。它通过 structured_method 参数区分处理模式：传入 JSON Schema 时使用 JSON 模式，传入 CFG 时使用 CFG 模式。服务端在收到请求后：

1. 文法编译：将结构化约束（JSON Schema 或 CFG）编译为 Lark 的内部解析表
2. 约束注入：通过特殊的 token 序列将文法约束嵌入到 LLM 的推理过程中
3. 输出验证：模型生成完成后，在服务端再次用 Lark 验证输出是否符合文法，若不符合则触发重试或报错

这种方案比纯 prompt engineering 的成功率要高得多，因为它在模型推理层面就引入了格式约束，而不仅仅是「在 prompt 里写清楚格式」。

四、适用场景与受众分析

适合的场景

场景	说明
ETL 数据管道	从非结构化文本（PDF、网页、日志）中抽取结构化数据，无需后处理
API 数据生成	为测试环境生成符合接口 schema 的 mock 数据
对话信息抽取	从客服对话、聊天记录中提取订单信息、用户画像
数据标注辅助	用 LLM 辅助标注，再用 Trex 保证标注结果格式统一
多语言模型输出统一	不同 LLM 通过同一 Trex 接口可输出格式一致的结果

不适合的场景

Trex 本质上是一个云端 API 的客户端库，它无法独立运行——所有推理都在 Automorphic AI 的云端完成。这意味着：

• 如果你有数据隐私要求（数据不能发送到第三方），Trex 不适用
• 如果你需要毫秒级延迟，云端往返的网络开销可能超出预算
• 如果你想完全本地部署，目前 Automorphic AI 需要联系官方单独部署（email: founders@automorphic.ai）

五、代码质量评估

Trex 的代码规模非常精简，核心逻辑集中在一个 core.py 文件（约 200 行），加上异常定义和 __init__.py，总代码量在 300 行以内。这种「小而精」的设计有几个特点值得注意：

优点：

• 依赖极简：仅依赖 requests，无需重机器学习库
• API 设计清晰：3 个核心方法（generate、generate_cfg、generate_json），职责单一
• 错误处理完善：区分了 API Key 错误（401）、配置错误（CFG 无效）和通用错误
• 类型标注：使用 Python 3.10+ 的 str | dict 类型联合语法

不足：

• 测试覆盖缺失：仓库中没有 tests/ 目录，无法评估单元测试覆盖率
• 文档深度有限：README 主要是使用示例，缺乏架构设计说明和常见问题
• 不支持流式输出：当前 API 是一次性返回完整结果，无 streaming 支持

六、行业意义与竞争格局

在 LLM 应用工程化领域，「让模型输出结构化数据」是一个公认的基础需求。解决这个问题的主流方案包括：

• OpenAI 的 response_format 参数：GPT-4 Turbo 开始支持原生 JSON mode，但仅限 OpenAI 自家模型
• Guidance 库（Microsoft）：通过自定义生成语言在本地约束输出格式，支持 openai、anthropic、llama.cpp 等
• Outlines（Normal Computing）：类似 Guidance，侧重本地推理场景
• Trex：专注于云端 API，依赖 Automorphic AI 的推理基础设施

Trex 的差异化在于开箱即用——不需要配置本地模型、不需要 GPU，通过 pip install 加上一个 API Key 就能用。代价是失去了对模型和推理过程的控制，且依赖第三方服务可用性。

七、快速上手

安装（3 分钟）：

pip install git+https://github.com/automorphic-ai/trex.git

获取 API Key： 访问 automorphic.ai 注册账号，免费获取 Key。

验证安装：

import trex
tx = trex.Trex('<YOUR_API_KEY>')
schema = {"type": "object", "properties": {"msg": {"type": "string"}}}
result = tx.generate_json("Say hello", json_schema=schema)
print(result.response)  # {'msg': '...'}

项目信息：

• 语言：Python（仅 3 个源文件，总代码约 300 行）
• 协议：MIT
• 依赖：requests（仅此一个）
• 主要技术栈：Lark CFG 解析器 + Automorphic AI 云端推理
• Topics：llm large-language-models json regex etl unstructured-data

---

Trex 项目由 Automorphic AI 维护，是一个专注于「让 LLM 100% 遵循格式约束」的 Python 客户端库。适合需要在数据管道、ETL、信息抽取等场景中可靠处理 LLM 结构化输出的开发者。