Acceso a datos en funciones de IA

Al crear funciones de IA, es posible que tenga que acceder a datos contextuales más allá de los parámetros proporcionados por el modelo de IA. La Microsoft.Extensions.AI biblioteca proporciona varios mecanismos para pasar datos a delegados de función.

clase AIFunction

El AIFunction tipo representa una función que se puede describir en un servicio de IA e invocar. Puede crear AIFunction objetos llamando a una de las AIFunctionFactory.Create sobrecargas. Pero AIFunction también es una clase base, y puede derivar de ella e implementar su propio tipo de función de IA. DelegatingAIFunction proporciona una manera sencilla de encapsular un AIFunction existente y añadir funcionalidad adicional en capas, incluida la captura de datos adicionales que se van a utilizar.

Paso de datos

Puede asociar datos a la función en el momento en que se crea, ya sea mediante cierre o a través de AdditionalProperties. Si va a crear su propia función, puede rellenar AdditionalProperties como desee. Si usa AIFunctionFactory para crear la función, puede rellenar los datos mediante AIFunctionFactoryOptions.AdditionalProperties.

También puede capturar cualquier referencia a datos como parte del delegado proporcionado a AIFunctionFactory. Es decir, puedes incluir todo lo que quieras referenciar como parte del propio AIFunction.

Acceso a datos en delegados de función

Puede llamar a AIFunction directamente, o puede llamarlo indirectamente mediante FunctionInvokingChatClient. En las secciones siguientes se describe cómo acceder a los datos de argumento mediante cualquier enfoque.

Invocación de función manual

Si invoca manualmente un AIFunction llamando a AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken), pasa AIFunctionArguments. El AIFunctionArguments tipo incluye:

• Diccionario de argumentos con nombre.
• Context: un arbitrario IDictionary<object, object> para pasar datos ambientales adicionales a la función.
• Services: Un IServiceProvider que permite al AIFunction resolver el estado arbitrario desde un contenedor de inserción de dependencias (DI).

Si desea acceder a AIFunctionArguments o IServiceProvider desde su delegado AIFunctionFactory.Create, cree un parámetro con el tipo IServiceProvider o AIFunctionArguments. Ese parámetro se enlazará a los datos pertinentes del AIFunctionArguments al pasarlos a AIFunction.InvokeAsync().

El código siguiente muestra un ejemplo:

Delegate getWeatherDelegate = (AIFunctionArguments args) =>
{
    // Access named parameters from the arguments dictionary.
    string? location = args.TryGetValue("location", out object? loc) ? loc.ToString() : "Unknown";
    string? units = args.TryGetValue("units", out object? u) ? u.ToString() : "celsius";

    return $"Weather in {location}: 35°{units}";
};

// Create the AIFunction.
AIFunction getWeather = AIFunctionFactory.Create(getWeatherDelegate);

// Call the function manually.
var result = await getWeather.InvokeAsync(new AIFunctionArguments
{
    { "location", "Seattle" },
    { "units", "F" }
});
Console.WriteLine($"Function result: {result}");

CancellationToken también se trata como un caso especial: si el AIFunctionFactory.Create delegado o lambda tiene un CancellationToken parámetro, se enlazará al CancellationToken que se pasó a AIFunction.InvokeAsync().

Invocación a través de FunctionInvokingChatClient

FunctionInvokingChatClient publica el estado sobre la invocación actual en FunctionInvokingChatClient.CurrentContext, incluyendo no solo los argumentos, sino también todos los objetos de entrada de ChatMessage, los detalles de ChatOptions y sobre qué función se está invocando (de cuántas). Puede agregar los datos que desee en ChatOptions.AdditionalProperties y extraerlos desde FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties dentro de su AIFunction.

El código siguiente muestra un ejemplo:

FunctionInvokingChatClient client = new FunctionInvokingChatClient(
    new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(apiKey))
    .GetChatClient(model).AsIChatClient());

AIFunction getWeather = AIFunctionFactory.Create(() =>
    {
        // Access named parameters from the arguments dictionary.
        AdditionalPropertiesDictionary props =
            FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties;

        string location = props["location"].ToString();
        string units = props["units"].ToString();

        return $"Weather in {location}: 35°{units}";
    });

var chatOptions = new ChatOptions
{
    Tools = [getWeather],
    AdditionalProperties = new AdditionalPropertiesDictionary {
        ["location"] = "Seattle",
        ["units"] = "F"
    },
};

List<ChatMessage> chatHistory = [
    new(ChatRole.System, "You're a helpful weather assistant.")
];
chatHistory.Add(new ChatMessage(ChatRole.User, "What's the weather like?"));

ChatResponse response = await client.GetResponseAsync(chatHistory, chatOptions);
Console.WriteLine($"Response: {response.Text}");

Inserción de dependencia

Si usa FunctionInvokingChatClient para invocar funciones automáticamente, ese cliente configura un objeto AIFunctionArguments que pasa a AIFunction. Dado que AIFunctionArguments incluye el IServiceProvider que FunctionInvokingChatClient fue proporcionado, si construye su cliente mediante medios estándar de inyección de dependencias, dicho IServiceProvider se transfiere íntegramente hasta su AIFunction. En ese momento, puede consultarlo para lo que desee de DI.

Técnicas avanzadas

Si desea un control más detallado sobre cómo se enlazan los parámetros, puede usar AIFunctionFactoryOptions.ConfigureParameterBinding, lo que le permite controlar cómo se rellena cada parámetro. Por ejemplo, el SDK de C# de MCP usa esta técnica para enlazar automáticamente parámetros desde DI.

Si usa la AIFunctionFactory.Create(MethodInfo, Func<AIFunctionArguments,Object>, AIFunctionFactoryOptions) sobrecarga, también puede ejecutar su propia lógica arbitraria al crear el objeto de destino en el que se llamará al método de instancia cada vez. Y puede configurar esa instancia de la forma que quiera.