Outlines Regex DSL 完全指南：用对象组合替代正则字符串，构建可读、可调试的结构化输出约束

Outlines Regex DSL 完全指南用对象组合替代正则字符串构建可读、可调试的结构化输出约束【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlines导读正则表达式是描述文本格式最强大的工具但冗长的字符串拼接往往难以阅读和维护。Outlines 在 src/outlines/types/dsl.py 中提供了一套基于对象的正则表达式领域特定语言Regex DSL所有正则组件都是Term对象可以通过String、Regex、量化方法与、either()等算子以树状结构组合最终再统一编译回标准正则字符串。这套 DSL 不仅适用于日常的输入校验还能直接作为字段类型嵌入 Pydantic 模型把正则模式翻译成 JSON Schema 的pattern约束进而用于约束大语言模型LLM的生成输出。读完本文你将掌握所有Term构建块、七大量化方法、组合算子、内置常用类型integer、uuid4、ipv4、sentence 等并理解它如何通过to_regex与generator管线衔接实现 Structured Outputs。为什么需要一套正则 DSL直接写正则字符串虽然强大但在复杂场景下存在明显痛点模块化与可读性与其书写晦涩的正则字符串不如把表达式组合成一棵对象树每个节点职责单一。可调试性每个表达式都可以打印成 ASCII 树状结构复杂正则在出错时能直观定位层级与顺序问题。与 Pydantic 无缝集成DSL 定义的表达式可以直接作为 Pydantic 模型字段类型自动转换为 JSON Schema 中带pattern约束的string字段并承担运行时校验见 src/outlines/types/dsl.py 中validate与__get_pydantic_json_schema__的实现。可扩展性所有量化器、组合器都是Term的子类dataclass新增一种组合逻辑只需继承并实现对应的_display_node与to_regex分支。从源码结构看该模块src/outlines/types/dsl.py承担三层职责定义Term及其子类、把 Python 类型转换为Termpython_types_to_terms、把Term编译回正则字符串to_regex。核心构建块String 与 RegexDSL 中的每个正则组件都是一个Term基类定义见 src/outlines/types/dsl.py。两种最基础的 Term 为String字面量字符串。由于它会在编译时对字符串中所有正则元字符做转义to_regex中调用re.escape见 src/outlines/types/dsl.pyString(a.b)匹配的是字面a.b而非通配符。Regex直接包装一段既有的正则模式字符串编译时会被整体加括号包裹f({term.pattern})见 src/outlines/types/dsl.py保证优先级正确。from outlines.types import String, Regex # 一个字面量字符串 hello literal String(hello) # 内部表示为 hello # 一个匹配一个或多个数字的正则模式 digit Regex(r[0-9]) # 内部表示为 [0-9] # 转换回标准正则字符串 from outlines.types.dsl import to_regex print(to_regex(literal)) # 输出: hello print(to_regex(digit)) # 输出: ([0-9])需要注意to_regex对Regex会额外包裹一对括号因此上面第二个输出实际为([0-9])而String则仅做转义不包裹。这一点在 tests/types/test_to_regex.py 中有对应断言to_regex(Regex([0-9])) ([0-9])。量化器控制匹配次数DSL 把正则的量词统一实现为Term上的方法同时也提供同名的顶层函数版本函数版本会自动把普通字符串参数包装成String对象因此String(foo).optional()与optional(foo)完全等价。所有量化器的类定义与编译逻辑分别在 src/outlines/types/dsl.pyKleeneStar、KleenePlus、Optional、QuantifyExact、QuantifyMinimum、QuantifyMaximum、QuantifyBetween和 src/outlines/types/dsl.pyto_regex的对应分支中。exactly(count)精确匹配 count 次# 方法形式恰好 5 个数字 five_digits Regex(r\d).exactly(5) print(to_regex(five_digits)) # 输出: ((\d)){5} # 函数形式 from outlines.types import exactly five_digits exactly(Regex(r\d), 5) print(to_regex(five_digits)) # 输出: ((\d)){5}optional()匹配零次或一次# 方法形式单词末尾可选的 s maybe_s String(s).optional() print(to_regex(maybe_s)) # 输出: (s)? # 函数形式 from outlines.types import optional maybe_s optional(s) print(to_regex(maybe_s)) # 输出: (s)?one_or_more()Kleene Plus至少一次# 方法形式一个或多个字母字符 letters Regex(r[A-Za-z]).one_or_more() print(to_regex(letters)) # 输出: ([A-Za-z]) # 函数形式 from outlines.types import one_or_more letters one_or_more(Regex(r[A-Za-z])) print(to_regex(letters)) # 输出: ([A-Za-z])zero_or_more()Kleene Star零次或多次# 方法形式零个或多个空格 spaces String( ).zero_or_more() print(to_regex(spaces)) # 输出: ( )* # 函数形式 from outlines.types import zero_or_more spaces zero_or_more( ) print(to_regex(spaces)) # 输出: ( )*between(min_count, max_count)区间匹配含两端# 方法形式2 到 4 个单词字符 word_chars Regex(r\w).between(2, 4) print(to_regex(word_chars)) # 输出: (\w){2,4} # 函数形式 from outlines.types import between word_chars between(Regex(r\w), 2, 4) print(to_regex(word_chars)) # 输出: (\w){2,4}at_least(count)至少 count 次# 方法形式至少 3 个数字 at_least_three Regex(r\d).at_least(3) print(to_regex(at_least_three)) # 输出: (\d){3,} # 函数形式 from outlines.types import at_least at_least_three at_least(Regex(r\d), 3) print(to_regex(at_least_three)) # 输出: (\d){3,}at_most(count)至多 count 次# 方法形式至多 3 个数字 up_to_three Regex(r\d).at_most(3) print(to_regex(up_to_three)) # 输出: (\d){0,3} # 函数形式 from outlines.types import at_most up_to_three at_most(Regex(r\d), 3) print(to_regex(up_to_three)) # 输出: (\d){0,3}注意at_most(count)编译出的区间下限固定为 0f(...){0,{max}}见 src/outlines/types/dsl.py这与正则语义一致。量化参数的合法性校验从源码看四个Quantify*类都在__post_init__中做了参数校验src/outlines/types/dsl.pyexactly、at_least、at_most的计数必须为非负整数否则抛出ValueErrorbetween额外要求min_count max_count。这保证了 DSL 构造出的表达式不会出现非法区间。与测试的一致性验证tests/types/test_to_regex.py 对这些量化器逐一做了断言例如QuantifyExact(String(a), 2)编译为(a){2}且a不匹配、aa匹配、aaa不匹配QuantifyMaximum编译为(a){0,2}。这些测试同时验证了每个 Term 的matches()方法基于re.fullmatch见 src/outlines/types/dsl.py——注意它要求整体完全匹配而非部分匹配。组合算子连接与选择连接与__radd__运算符把两个 Term 按顺序连接成一个Sequence。实现上无论是Term str还是str Term字符串一侧都会被自动包装成String见 src/outlines/types/dsl.py 的__add__与__radd__。# 匹配 hello world pattern String(hello) Regex(r\w) print(to_regex(pattern)) # 输出: hello\ (\w)String(hello)中的空格被转义为\Regex(r\w)被包装为(\w)两者按序拼接。Sequence在to_regex中的处理是逐个子项编译后直接拼接src/outlines/types/dsl.py。选择either()与|either(*terms)工厂函数创建一个Alternatives节点匹配多个候选项中的任意一个候选项数量不限。普通字符串参数同样会被自动包装为String以转义正则元字符src/outlines/types/dsl.py。from outlines.types import either # 匹配 cat、dog 或 mouse animal either(String(cat), dog, mouse) print(to_regex(animal)) # 输出: (cat|dog|mouse)此外Term还实现了__or__/__ror__src/outlines/types/dsl.py因此也可以直接写Regex(rcat) | dog。Alternatives编译为(a|b|c)形式src/outlines/types/dsl.py。内置类型开箱即用的常见文本格式DSL 预置了一批直接可用的Regex常量定义在 src/outlines/types/init.py并通过outlines.types顶层命名空间导出完整清单见 src/outlines/types/init.py。类型匹配内容integer与 Pythonint识别的整数一致[-]?(0\|[1-9][0-9]*)即无前导零除 0 本身booleanTrue或False与bool的字符串表示一致number浮点数integer后可选小数部分与指数部分dateYYYY-MM-DD月份、日期有合法范围校验timeHH:MM:SS时分秒均在合法范围内datetimedate 空格 timedigit单个数字\dchar单个单词字符\wnewline换行符兼容 Linux / Windows / macOS\r\n、\r、\nwhitespace空白字符\shex_str十六进制字符串可选0x前缀uuid4UUID v4格式xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxxipv4IPv4 地址每段 0–255 且段间以.分隔sentence一句话以大写字母开头、以./!/?结尾paragraph段落一句或多句句间以空白分隔、以换行结束除表中列出的之外仓库还内置了ipv6RFC 4291 完整八组冒号十六进制、::压缩及 IPv4 映射形式见 src/outlines/types/init.py、semverSemVer 2.0.0 主版本号规则、mac_address冒号分隔六段 EUI-48、hex_color#rgb/#rrggbb、slug小写连字符 URL 片段、credit_card按发卡行前缀区分的卡号格式、emailRFC 5322 兼容与isbn等全部声明于 src/outlines/types/init.py。由于这些内置类型本身是Regex即Term它们天然支持量化与组合。例如描述 GSM8K 数据集的答案格式from outlines.types import sentence, digit answer A: sentence.between(2, 4) So the answer is: digit.between(1, 4)注意这里sentence与digit之间是between(2, 4)表示匹配 2–4 句、2–4 位数字。实战示例示例 1匹配自定义 ID 格式要求匹配形如ID-12345的 ID开头是字面量ID-后跟恰好 5 位数字。id_pattern ID- Regex(r\d).exactly(5) print(to_regex(id_pattern)) # 输出: ID-((\d)){5}开头的普通字符串ID-会被__radd__自动包装成String并转义-实际输出中ID-中的连字符转义与否取决于re.escape的结果模式语义为字面ID-。示例 2在 Pydantic 模型中做 Email 校验DSL 表达式的最大价值在于可以直接用作 Pydantic 字段类型Term.__get_pydantic_core_schema__会把校验逻辑注册为 plain validator__get_pydantic_json_schema__则生成{type: string, pattern: ...}见 src/outlines/types/dsl.py。from pydantic import BaseModel, ValidationError from outlines.types import Regex # 定义一个简化的 email 正则项 email_regex Regex(r[a-zA-Z0-9_.-][a-zA-Z0-9-]\.[a-zA-Z0-9-.]) class User(BaseModel): name: str email: email_regex # 直接以 DSL 表达式作为字段类型 # 合法输入 user User(nameAlice, emailaliceexample.com) print(user) # 非法输入触发 ValidationError try: User(nameBob, emailnot-an-email) except ValidationError as e: print(e)字段的 JSON Schema 会自动带上pattern约束运行时校验则基于re.fullmatch整个字符串必须完全匹配。测试 tests/types/test_dsl.py 验证了BaseModel中 DSL 字段的 JSON Schema 生成行为例如Regex(a)对应{pattern: a, type: string}。若要使用更严格的 RFC 5322 校验也可以直接使用仓库内置的outlines.types.email。示例 3构建复杂日期模式用连接与量化组合出YYYY-MM-DDyear Regex(r\d).exactly(4) # 年份 4 位 month Regex(r\d).exactly(2) # 月份 2 位 day Regex(r\d).exactly(2) # 日期 2 位 date_pattern year - month - day print(to_regex(date_pattern)) # 输出类似: ((\d)){4}-((\d)){2}-((\d)){2}更严格的场景可以直接使用内置date类型它会校验月份 01–12 与日期 01–31 的取值范围见 src/outlines/types/init.py。可视化你的表达式ASCII 树每个Term都实现了display_ascii_tree()通过__str__可以直接打印对象获得表达式的树状结构基类实现见 src/outlines/types/dsl.py各子类的_display_node/_display_children定义了节点标签与缩进层级。# 使用连接与量化构造的组合模式 pattern a String(b).one_or_more() c print(pattern)预期输出└── Sequence ├── String(a) ├── KleenePlus() │ └── String(b) └── String(c)树中每个节点清晰呈现层级与顺序Sequence下有String(a)、KleenePlus()其子节点是String(b)与String(c)。_display_children通过is_last参数控制└──与├──分支符src/outlines/types/dsl.py因此复杂嵌套表达式也能精确还原结构。从 DSL 到结构化生成与 generator 的衔接这套 DSL 并非孤立工具——它正是 Outlines 结构化生成的底层类型系统之一。在 src/outlines/generator.py 中当传入的output_type不是 CFG 或 JSON Schema 时生成器会调用python_types_to_terms(output_type)得到Term再通过to_regex(term)编译出正则字符串交给get_regex_logits_processor在解码阶段约束每一步 token 采样。换句话说src/outlines/types/dsl.py 的python_types_to_terms还能把int、str、Literal、Union、List、Tuple、Dict、Enum、Pydantic 模型、TypedDict、dataclass 等 Python 类型递归翻译为 DSLTerm从而让Regex(r\d).exactly(5)这类表达式与 Python 类型标注统一进入同一条结构化生成管线。这也解释了为什么文档明确建议用 DSL 约束 LLM 输出相比直接传原始正则字符串DSL 提供了组合、量化和可视化能力同时最终仍能无缝降级为标准正则交给后端处理器。小结Outlines 的 Regex DSL 用一组Term对象把正则表达式从难以维护的字符串变成可组合、可调试、可扩展的类型系统构建块String字面量自动转义与Regex原生模式是所有表达式的原子。量化器exactly、optional、one_or_more、zero_or_more、between、at_least、at_most既可以是方法也可以是函数且自动做字符串包装与参数合法性校验。组合连接与either()/|选择支持任意嵌套。内置类型从integer、uuid4、ipv4到sentence、paragraph、email覆盖了绝大多数常见文本格式。集成能力直接作为 Pydantic 字段类型完成校验并生成pattern约束或经 src/outlines/generator.py 成为 LLM 结构化输出Structured Outputs的约束来源。相关实现与测试可进一步查阅 src/outlines/types/dsl.py、src/outlines/types/init.py、tests/types/test_to_regex.py 与 tests/types/test_dsl.py以及 DSL 在 docs/features/core/output_types.md 对应的类型系统文档。【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlines创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考