结构化输出
根据提供的 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:
现在你可以在结构化输出类中使用该规则:
最后更新于

