Acessar dados em funções de IA

Ao criar funções de IA, talvez seja necessário acessar dados contextuais além dos parâmetros fornecidos pelo modelo de IA. A Microsoft.Extensions.AI biblioteca fornece vários mecanismos para passar dados para delegados de função.

Classe AIFunction

O AIFunction tipo representa uma função que pode ser descrita para um serviço de IA e invocada. Você pode criar AIFunction objetos chamando uma das AIFunctionFactory.Create sobrecargas. Mas AIFunction também é uma classe base e você pode derivar dela e implementar seu próprio tipo de função de IA. DelegatingAIFunction fornece uma maneira fácil de envolver um AIFunction existente e adicionar funcionalidade extra, incluindo a captura de dados adicionais a serem usados.

Passar dados

Você pode associar dados à função no momento em que ela é criada, por meio de fechamento ou via AdditionalProperties. Se você estiver criando sua própria função, poderá preencher AdditionalProperties como desejar. Se você usar AIFunctionFactory para criar a função, poderá preencher dados usando AIFunctionFactoryOptions.AdditionalProperties.

Você também pode capturar todas as referências aos dados como parte do delegado fornecido para AIFunctionFactory. Ou seja, você pode incorporar tudo o que quiser referenciar como parte do próprio AIFunction.

Acessar dados em delegados de função

Você pode chamar AIFunction diretamente, ou pode chamá-lo indiretamente usando FunctionInvokingChatClient. As seções a seguir descrevem como acessar dados de argumento usando qualquer abordagem.

Invocação de função manual

Se você invocar manualmente um AIFunction chamando AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken), passará AIFunctionArguments. O AIFunctionArguments tipo inclui:

• Um dicionário de argumentos nomeados.
• Context: um valor arbitrário IDictionary<object, object> para passar dados contextuais adicionais para a função.
• Services: um IServiceProvider que permite que o AIFunction resolva o estado arbitrário a partir de um contêiner de injeção de dependência (DI).

Se você quiser acessar o AIFunctionArguments ou o IServiceProvider de dentro do delegado AIFunctionFactory.Create , crie um parâmetro tipado como IServiceProvider ou AIFunctionArguments. Esse parâmetro será associado aos dados relevantes do AIFunctionArguments passado para AIFunction.InvokeAsync().

O código a seguir mostra um exemplo:

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 também é especial: se o AIFunctionFactory.Create delegado ou lambda tiver um CancellationToken parâmetro, ele será associado ao CancellationToken que foi passado para AIFunction.InvokeAsync().

Invocação por meio de FunctionInvokingChatClient

FunctionInvokingChatClient publica o estado sobre a invocação atual para FunctionInvokingChatClient.CurrentContext, incluindo não apenas os argumentos, mas todos os objetos de entrada ChatMessage , o ChatOptionse os detalhes sobre qual função está sendo invocada (de quantos). Você pode adicionar quaisquer dados que desejar em ChatOptions.AdditionalProperties e extrair esses dados dentro do seu AIFunction do FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties.

O código a seguir mostra um exemplo:

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}");

Injeção de dependência

Se você usar FunctionInvokingChatClient para invocar funções automaticamente, esse cliente configurará um AIFunctionArguments objeto que ele passa para o AIFunction. Como AIFunctionArguments inclui o IServiceProvider que o FunctionInvokingChatClient foi fornecido, se você construir seu cliente usando os meios padrão de DI, IServiceProvider será totalmente transferido para o seu AIFunction. Nesse ponto, você pode consultá-lo para qualquer coisa que desejar da DI.

Técnicas avançadas

Se você quiser um controle mais refinado sobre como os parâmetros são associados, você pode usar AIFunctionFactoryOptions.ConfigureParameterBinding, o que o coloca no controle sobre como cada parâmetro é preenchido. Por exemplo, o MCP C# SDK usa essa técnica para associar automaticamente parâmetros de DI.

Se você usar a sobrecarga AIFunctionFactory.Create(MethodInfo, Func<AIFunctionArguments,Object>, AIFunctionFactoryOptions), poderá também executar sua própria lógica arbitrária a cada vez que criar o objeto de destino no qual o método de instância será chamado. E você pode fazer o que quiser para configurar essa instância.