Salida estructurada

Impón la salida del agente según el esquema proporcionado.

PRERREQUISITOS

Esta guía supone que ya estás familiarizado con los siguientes conceptos:

• Agente

• Llamada de herramienta y función

Hay muchos casos de uso en los que necesitamos que los agentes entiendan el lenguaje natural, pero produzcan una formato estructurado. Un caso de uso común es extraer datos de texto para insertarlos en una base de datos o usarlos con algún otro sistema posterior. Esta guía cubre cómo Neuron permite imponer salidas estructuradas desde el agente.

Cómo usar la salida estructurada

El concepto central es que la estructura de salida de las respuestas del LLM necesita representarse de alguna manera. El esquema contra el que Neuron valida se define mediante anotaciones de tipos de PHP. Básicamente, tienes que definir una clase con propiedades estrictamente tipadas:

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que al usuario le encanta comer.', 
        required: false
    )]
    public string $preference;
}

Neuron genera el esquema JSON correspondiente a partir del objeto PHP para instruir al modelo subyacente sobre el formato de datos que necesitas. Luego, el agente analiza la salida del LLM para extraer los datos y devuelve una instancia del objeto rellenada con los valores adecuados:

use NeuronAI\Chat\Messages\UserMessage;

// Hablar con el agente solicitando la salida estructurada
$person = MyAgent::make()->structured(
    new UserMessage("¡Soy John y me gusta la pizza!"),
    Person::class
);

echo $person->name.' le gusta '.$person->preference;
// John le gusta la pizza

Clase de salida predeterminada

También puedes encapsular el formato de salida dentro de la implementación del Agente, de modo que sea el formato de salida estándar del Agente. Siempre necesitas llamar al structured() método para exigir una salida estricta.

use NeuronAI\Chat\Messages\UserMessage;

// Encapsular el formato de salida predeterminado 
class MyAgent extends Agent
{
    ...

    protected function getOutputClass(): string
    {
        return Person::class;
    }
}

// Usa siempre el método structured si quieres obtener salida estructurada
$person = MyAgent::make()
    ->structured(new UserMessage("Soy John y me gusta la pizza"));

echo $person->name.' le gusta '.$person->preference;
// John le gusta la pizza

Controlar la generación de salida

Neuron requiere que definas dos capas de reglas para crear la clase de salida estructurada.

La primera es el SchemaProperty atributo que te permite controlar el esquema JSON enviado al LLM para entender el formato de datos requerido.

La segunda capa es la validación. Los atributos de validación garantizarán que los datos obtenidos de la respuesta del LLM sean coherentes con tus requisitos.

SchemaProperty

El SchemaProperty atributo te permite definir los parámetros del esquema JSON de cada propiedad:

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.',
        required: true,
        minLength: 3,
        maxLength: 255,
    )]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que al usuario le encanta comer.', 
        required: false,
        min: 18,
        max: 64,
    )]
    public ?int $age = null;
}

Clase anidada

Puedes construir estructuras de salida complejas usando otros objetos PHP como tipo de propiedad. Siguiendo el ejemplo de la Person clase, podemos añadir la dirección propiedad tipada como otra clase estructurada.

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Property;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Valid;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    #[NotBlank]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que al usuario le encanta comer.', 
        required: true
    )]
    public string $preference;
    
    #[SchemaProperty(
        description: 'La dirección para completar la entrega.', 
        required: true
    )]
    public Address $address;
}

En el Address En esta definición requerimos solo las propiedades de calle y código postal, y permitimos que la ciudad esté vacía.

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Address
{
    #[SchemaProperty(
        description: 'El nombre de la calle.', 
        required: true
    )]
    #[NotBlank]
    public string $street;

    #[SchemaProperty(
        description: 'El nombre de la ciudad.', 
        required: false
    )]
    public string $city;

    #[SchemaProperty(
        description: 'El código postal de la dirección.', 
        required: true
    )]
    #[NotBlank]
    public string $zip;
}

Ahora, cuando pidas al agente la salida estructurada, obtendrás de vuelta la instancia rellenada:

use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Observability\AgentMonitoring;

// Hablar con el agente solicitando la salida estructurada
$person = MyAgent::make()->structured(
    new UserMessage("¡Soy John y quiero una pizza en st. James Street 00560!"),
    Person::class
);

echo $person->name.' le gusta '.$person->preference.'. Dirección: '.$person->address->street;
// John le gusta la pizza. Dirección: st.James Street

Array

Si declaras una propiedad como un array, Neuron asume que la lista de elementos es una lista de cadenas. Si quieres que el array contenga una lista de otros objetos estructurados, puedes especificarlo usando el anyOf argumento:

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    #[NotBlank]
    public string $name;
    
    #[SchemaProperty(
        description: 'La lista de etiquetas para el perfil del usuario.', 
        required: true,
        anyOf: [Tag::class]
    )]
    public array $tags;
}

Y aquí está la implementación hipotética de la Tag clase con sus propias reglas de validación e información de propiedades:

<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Tag
{
    #[SchemaProperty(
        description: 'El nombre de la etiqueta', 
        required: true,
    )]
    #[NotBlank]
    public string $name;
}

Array con múltiples tipos

Como puedes notar en el ejemplo anterior, el argumento anyOf es un array. Neuron también admite la composición de arrays con múltiples tipos de objetos. Solo enumera los objetos estructurados que el array puede contener y Neuron incluirá todas sus especificaciones en el esquema JSON para el LLM.

class Report
{
    #[SchemaProperty(
        description: 'El contenido del informe', 
        required: true,
        anyOf: [TextBlock::class, TableBlock::class, ImageBlock::class]
    )]
    public array $content;
}

Máximo de reintentos

Dado que los LLM no son perfectamente deterministas, es obligatorio contar con un mecanismo de reintento si falta algo en la respuesta del LLM.

Por defecto, Neuron extrae y valida los datos de la respuesta del LLM y, si hay uno o más errores de validación, reintenta automáticamente la solicitud una sola vez más, informando al LLM de lo que salió mal y para qué propiedades.

Eventualmente puedes personalizar cuántas veces el agente debe reintentar para obtener una respuesta correcta del LLM:

$person = MyAgent::make()->structured(
    messages: new UserMessage("Soy John y me gusta la pizza!"),
    class: Person::class,
    maxRetries: 3
);

Si trabajas con un LLM menos capaz, considera usar un número de reintentos que equilibre la probabilidad de obtener una respuesta válida y el consumo potencial de tokens.

Puedes desactivar los reintentos simplemente pasando cero. Será un intento de una sola vez:

$person = MyAgent::make()->structured(
    messages: new UserMessage("Soy John y me gusta la pizza!"),
    class: Person::class,
    maxRetries: 0
);

Monitorización y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán varios pasos con múltiples invocaciones de llamadas a LLM. A medida que estas aplicaciones se vuelven cada vez más complejas, resulta crucial poder inspeccionar exactamente qué está ocurriendo dentro de tu sistema agéntico. La mejor manera de hacerlo es con Inspector.

Neuron AI | Inspectordocs.inspector.dev

Cada segmento aporta su propia información de depuración para seguir la ejecución del agente en tiempo real:

Aprende cómo habilitar la observabilidad en la siguiente sección.

Reglas de validación

Dado que los LLM son sistemas no deterministas y la coherencia de su salida puede verse muy influida por la calidad del contexto que tienen como entrada, y aún pueden alucinar, proporcionamos un conjunto de reglas de validación que puedes añadir a las propiedades de clases estructuradas para instruir a Neuron a verificar el conjunto final de datos generado por el LLM.

Las reglas de validación permiten a Neuron reenviar la solicitud de generación al LLM varias veces con un informe detallado de lo que estaba mal si una o más propiedades no son válidas, hasta que alcanza el maxRetries valor.

Si no defines ninguna regla de validación, los datos extraídos de la respuesta del LLM se rellenarán directamente en la clase de salida estructurada.

#[NotBlank]

La propiedad bajo validación no puede estar vacía. Acepta la allowNull indicador para tratar explícitamente el valor null como equivalente a vacío o no.

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Person 
{
    #[NotBlank(allowNull: false)]
    public string $name;
}

#[Length]

Determina si la longitud de una cadena coincide con los criterios dados:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Length;

class Person 
{
    #[Length(min: 1, max: 10)]
    public string $name;
    
    #[Length(exactly: 5)]
    public string $zip_code;
}

#[WordsCount]

Determina si el número de palabras en una cadena coincide con los criterios dados:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\WordsCount;

class Person 
{
    #[WordsCount(exactly: 10)]
    public string $title;
    
    #[WordsCount(min: 1, max: 10)]
    public string $content;
}

#[Count]

Determina si el tamaño de un array coincide con los criterios dados:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Count;

class Person 
{
    #[Count(min: 1, max: 3)]
    public array $dogs;
    
    #[Count(exactly: 1)]
    public array $children;
}

#[EqualTo] - #[NotEqualTo]

Estas reglas tienen la misma estructura y significado, y aceptan un solo argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente igual (#[EqualTo]) o diferente (#[NotEqualTo]) que el valor de referencia:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\EqualTo;
use NeuronAI\StructuredOutput\Validation\Rules\NotEqualTo;

class Person 
{
    #[EqualTo(reference: 'Rome')]
    public string $city;
    
    #[NotEqualTo(reference: '00502')]
    public string $zip_code;
}

#[GreaterThan] - #[GreaterThanEqual]

Estas reglas tienen la misma estructura y significado, y aceptan un solo argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente mayor (#[GreaterThan]) o igual (#[GreaterThanEqual]) que el valor de referencia:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\GreaterThan;
use NeuronAI\StructuredOutput\Validation\Rules\GreaterThanEqual;

class Person 
{
    #[GreaterThan(reference: 17)]
    public int $age;
    
    #[GreaterThanEqual(reference: 1)]
    public int $cars;
}

#[LowerThan] - #[LowerThanEqual]

Estas reglas tienen la misma estructura y significado, y aceptan un solo argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente menor (#[LowerThan]) o igual (#[LowerThanEqual]) que el valor de referencia:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\LowerThan;
use NeuronAI\StructuredOutput\Validation\Rules\LowerThanEqual;

class Person 
{
    #[LowerThan(reference: 50)]
    public int $age;
    
    #[LowerThanEqual(reference: 1)]
    public int $cars;
}

#[OutOfRange]

Determina si un número está fuera del rango dado:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\InRange;

class Person 
{
    #[OutOfRange(min: 18, max: 35)]
    public int $age;
    
    // El argumento strict obliga a mantenerse estrictamente fuera de los límites del rango
    #[OutOfRange(min: 48, max: 54, strict: true)]
    public int $size;
}

#[IsFalse] - #[IsTrue]

La propiedad bajo validación debe tener exactamente el valor booleano definido por la regla:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IsFalse;
use NeuronAI\StructuredOutput\Validation\Rules\IsTrue;

class Phone
{
    #[IsFalse]
    public bool $iphone;
    
    #[IsTrue]
    public bool $refurbed;
}

#[IsNull] - #[IsNotNull]

La propiedad bajo validación debe respetar la condición de nullable definida por la regla:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IsNotNull;
use NeuronAI\StructuredOutput\Validation\Rules\IsNull;

class Phone
{
    #[IsNotNull]
    public string $brand;
    
    #[IsNull]
    public ?string $test;
}

#[Json]

La propiedad bajo validación debe contener una cadena JSON válida:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Json;

class Person
{
    #[Json]
    public string $address;
}

#[Url]

La propiedad bajo validación debe contener una URL válida:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Url;

class Person
{
    #[Url]
    public string $website;
}

#[Email]

La propiedad bajo validación debe contener una dirección de correo electrónico válida:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Email;

class Person
{
    #[Email]
    public string $email;
}

#[IpAddress]

La propiedad bajo validación debe contener una dirección IP válida:

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IpAddress;

class Spec
{
    #[IpAddress]
    public string $ip;
}

#[ArrayOf]

La propiedad bajo validación debe ser un array que contenga todos los objetos del tipo dado.

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\ArrayOf;

class Post
{
    #[ArrayOf(Tag::class)]
    public array $tags;
}

#[Regex]

La propiedad bajo validación debe respetar la expresión regular dada.

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Regex;

class Coupon
{
    #[Regex('/^[A-Z]{2}\d{4}$/')]
    public string $code;
}

Reglas de validación personalizadas

Las reglas de validación son atributos de PHP, así que para crear una nueva debes extender la clase AbstractValidationRule del framework y marcar la clase como un atributo de PHP:

namespace App\Neuron\Output;

use Attribute;
use NeuronAI\StructuredOutput\Validation\Rules\AbstractValidationRule;

#[Attribute(Attribute::TARGET_PROPERTY)]
class MyFormatRule extends AbstractValidationRule
{
    public function __construct(protected string $format)
    {
    }

    public function validate(string $name, mixed $value, array &$violations): void
    {
        if (!is_string($value)) {
            $violations[] = $this->buildMessage($name, '{name} debe ser una cadena.');
        } else if (!$this->respectFormat($this->format, $value)) {
            $violations[] = $this->buildMessage(
                $name,
                '{name} debe coincidir con el formato {format}',
                ['format' => $this->pattern]
            );
        }
    }
    
    protected function respectFormat(string $value)
    {
        ...
    }
}

Ahora puedes usar la regla en tu clase de salida estructurada:

namespace App\Neuron\Output;

class Route
{
    #[MyFormatRule('apps/{id}/show')]
    public string $path;
}