跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

结构化输出

根据提供的 schema 强制约束 Agent 输出。

编码代理技能

在许多场景中,我们需要 Agent 理解自然语言,但输出为 结构化格式。一个常见用例是从文本中提取数据,以插入数据库或供其他下游系统使用。本指南将介绍 Neuron 如何让你强制 Agent 输出结构化内容。

如何使用结构化输出

核心概念是,LLM 响应的输出结构需要以某种方式进行表示。Neuron 所验证的 schema 由 PHP 类型提示定义。基本上,你需要定义一个具有严格类型属性的类:

Neuron 会从 PHP 对象生成相应的 JSON schema,用来向底层模型说明你所需的数据格式。然后代理会解析 LLM 输出来提取数据,并返回一个填充了相应值的对象实例:

默认输出类

你也可以将输出格式封装到 Agent 的实现中,这样它就会成为该 Agent 的标准输出格式。你始终需要调用 structured() 方法来要求严格输出。

控制输出生成

Neuron 要求你定义两层规则来创建结构化输出类。

第一层是 SchemaProperty 属性,它允许你控制发送给 LLM 的 JSON schema,以便其理解所需的数据格式。

第二层是验证。验证属性可确保从 LLM 响应中收集到的数据与你的要求一致。

SchemaProperty

该 SchemaProperty 属性允许你定义每个属性的 JSON schema 参数:

使用 SchemaProperty 作为纯 PHP 属性并不能让你注入动态信息,例如来自数据库的信息,因为属性位于常规代码块之外。想象一下,你需要 schema 描述遵循用户的区域设置,而 PHP 属性无法做到这一点。

你的 DTO 类可以实现 SchemaPropertiesInterface 并提供静态方法 schemaProperties()。以属性名为键,值是 SchemaProperty 在运行时构建的对象:

解析规则:

  • 在 schemaProperties() 中列出的属性会使用该 SchemaProperty 对象(它会 替换 该属性上的整个属性配置——两者不会逐字段合并)。

  • 未列出的属性会回退到其 #[SchemaProperty] 属性(如果有的话)。

  • 下游行为与属性完全一致,包括 anyOf ——因此你甚至可以动态构建多态数组的类列表,而 反序列化器 会正确地将其填充

嵌套类

你可以使用其他 PHP 对象作为属性类型来构建复杂的输出结构。沿用 Person 类的示例,我们可以添加 address 属性,并将其类型设为另一个结构化类。

在 Address 定义中,我们只要求 street 和 zip code 属性,并允许 city 为空。

现在,当你向代理请求结构化输出时,你会得到已填充的实例:

数组

如果你将属性声明为数组,Neuron 会假定其中的项目列表是字符串列表。如果你希望数组包含其他结构化对象的列表,可以使用 anyOf 参数:

以下是 Tag 类的假设实现,包含其自身的验证规则和属性信息:

多类型数组

从上面的示例可以看出,anyOf 参数是一个数组。Neuron 也支持由多种对象类型组成的数组。只需列出数组可以包含的结构化对象,Neuron 就会把它们的所有规格包含到 LLM 的 JSON schema 中。

最大重试次数

由于 LLM 并非完全确定性的,如果 LLM 响应中缺少某些内容,就必须有重试机制。

默认情况下,Neuron 会从 LLM 响应中提取并验证数据,如果存在一个或多个验证错误,就会自动再重试一次请求,并向 LLM 说明哪里出错了,以及哪些属性有问题。

你最终可以自定义代理必须重试多少次才能从 LLM 获取正确答案:

如果你使用能力较弱的 LLM,可以考虑设置一个重试次数,在获得有效答案的概率和潜在的 token 消耗之间取得平衡。

如果传入 0,就可以禁用重试。这将是一次性尝试:

监控与调试

你使用 Neuron 构建的许多应用都会包含多个步骤以及多次 LLM 调用。随着这些应用变得越来越复杂,能够检查你的代理系统内部究竟发生了什么变得至关重要。做到这一点的最佳方式是使用 Inspector.

验证规则

由于 LLM 是非确定性系统,其输出的一致性会受到输入上下文质量的很大影响,而且它们仍可能产生幻觉,因此我们提供了一组验证规则,你可以将其添加到结构化类属性中,用来指示 Neuron 验证 LLM 生成的最终数据集。

如果一个或多个属性无效,验证规则允许 Neuron 多次将生成请求重新发送给 LLM,并附上详细报告说明哪里有问题,直到达到 maxRetries 值。

如果你没有定义任何验证规则,从 LLM 响应中提取的数据将直接填充到结构化输出类中。

#[NotBlank]

正在验证的属性不能为空。它接受 allowNull 标志,用于明确将 null 值视为空等价,或者不这样处理。

#[Length]

判断一个 字符串 是否符合给定条件:

#[WordsCount]

判断一个 字符串 是否符合给定条件:

#[Count]

判断一个 数组 是否符合给定条件:

#[EqualTo] - #[NotEqualTo]

这些规则具有相同的结构和含义,并接受一个参数来定义要比较的值。正在验证的属性必须严格等于(#[EqualTo])或不同于(#[NotEqualTo])参考值:

#[GreaterThan] - #[GreaterThanEqual]

这些规则具有相同的结构和含义,并接受一个参数来定义要比较的值。正在验证的属性必须严格大于(#[GreaterThan])或等于(#[GreaterThanEqual])参考值:

#[LowerThan] - #[LowerThanEqual]

这些规则具有相同的结构和含义,并接受一个参数来定义要比较的值。正在验证的属性必须严格小于(#[LowerThan])或等于(#[LowerThanEqual])参考值:

#[OutOfRange]

判断一个 数字 是否超出给定范围:

#[IsFalse] - #[IsTrue]

正在验证的属性必须恰好具有规则所定义的布尔值:

#[IsNull] - #[IsNotNull]

正在验证的属性必须符合规则定义的可空条件:

#[Json]

正在验证的属性必须包含有效的 JSON 字符串:

#[Url]

正在验证的属性必须包含有效的 URL:

#[Email]

正在验证的属性必须包含有效的电子邮件地址:

#[IpAddress]

正在验证的属性必须包含有效的 IP 地址:

#[ArrayOf]

正在验证的属性必须是一个包含所给对象类型全部元素的数组。注意,你还需要添加 doc-block,才能让代理实例化正确的类。在 doc-block 中使用完整的类命名空间。

#[Regex]

正在验证的属性必须符合给定的正则表达式。

自定义验证规则

验证规则是 PHP 属性,因此要创建新的规则,你应该继承框架的 AbstractValidationRule 并将该类标记为 PHP Attribute:

现在你可以在结构化输出类中使用该规则:

最后更新于