Condividi tramite

Accedere ai dati nelle funzioni di intelligenza artificiale

Quando si creano funzioni di intelligenza artificiale, potrebbe essere necessario accedere ai dati contestuali oltre i parametri forniti dal modello di intelligenza artificiale. La Microsoft.Extensions.AI libreria fornisce diversi meccanismi per passare i dati ai delegati di funzione.

Classe AIFunction

Il AIFunction tipo rappresenta una funzione che può essere descritta in un servizio di intelligenza artificiale e richiamata. È possibile creare AIFunction oggetti chiamando uno degli AIFunctionFactory.Create overload. Ma AIFunction è anche una classe base ed è possibile derivarla e implementare il proprio tipo di funzione di intelligenza artificiale. DelegatingAIFunction offre un modo semplice per eseguire il wrapping di un AIFunction esistente e per aggiungere funzionalità aggiuntive, includendo l'acquisizione di dati aggiuntivi da utilizzare.

Trasmettere i dati

È possibile associare i dati alla funzione al momento della creazione, tramite chiusura o tramite AdditionalProperties. Se stai creando una funzione personalizzata, puoi popolare AdditionalProperties come preferisci. Se si usa AIFunctionFactory per creare la funzione, è possibile popolare i dati usando AIFunctionFactoryOptions.AdditionalProperties.

È anche possibile acquisire qualsiasi riferimento ai dati come parte del delegato fornito a AIFunctionFactory. Cioè, puoi incorporare qualsiasi elemento che desideri riferire come parte della AIFunction stessa.

Accedere ai dati nei delegati di funzione

Puoi chiamare direttamente il AIFunction oppure indirettamente utilizzarlo con il FunctionInvokingChatClient. Le sezioni seguenti descrivono come accedere ai dati degli argomenti usando uno dei due approcci.

Chiamata di funzione manuale

Se si richiama manualmente un oggetto AIFunction chiamando AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken), si passa un parametro AIFunctionArguments. Il AIFunctionArguments tipo include:

Se vuoi accedere a AIFunctionArguments o IServiceProvider dall'interno del delegato AIFunctionFactory.Create, crea un parametro digitato come IServiceProvider o AIFunctionArguments. Tale parametro verrà associato ai dati pertinenti dall'oggetto AIFunctionArguments passato a AIFunction.InvokeAsync().

Il codice seguente illustra un esempio:

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 è un caso speciale: se il delegato o l'espressione AIFunctionFactory.Create lambda ha un CancellationToken parametro, verrà associato al CancellationToken passato a AIFunction.InvokeAsync().

Chiamata tramite FunctionInvokingChatClient

FunctionInvokingChatClient pubblica lo stato della chiamata corrente a FunctionInvokingChatClient.CurrentContext, inclusi non solo gli argomenti, ma anche tutti gli oggetti di input ChatMessage, gli ChatOptions e i dettagli su quale funzione viene richiamata (tra quante). È possibile aggiungere tutti i dati desiderati in ChatOptions.AdditionalProperties ed estrarli all'interno di AIFunction da FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties.

Il codice seguente illustra un esempio:

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

Iniezione delle dipendenze

Se si utilizza FunctionInvokingChatClient per richiamare automaticamente le funzioni, tale client configura un AIFunctionArguments oggetto che passa all'oggetto AIFunction. Poiché AIFunctionArguments include l'oggetto IServiceProviderFunctionInvokingChatClient con cui è stato fornito , se si costruisce il client usando l'inserimento delle dipendenze standard, questo IServiceProvider viene passato fino all'interno dell'oggetto AIFunction. A questo punto, è possibile eseguire una query per qualsiasi elemento desiderato da DI.

Tecniche avanzate

Se si desidera un controllo più granulare sulla modalità di associazione dei parametri, è possibile usare AIFunctionFactoryOptions.ConfigureParameterBinding, che consente di controllare il modo in cui ogni parametro viene popolato. Ad esempio, MCP C# SDK usa questa tecnica per associare automaticamente i parametri dalla DI.

Se si usa l'overload AIFunctionFactory.Create(MethodInfo, Func<AIFunctionArguments,Object>, AIFunctionFactoryOptions), è anche possibile eseguire una logica personalizzata ogni volta che si crea l'oggetto destinazione su cui verrà chiamato il metodo di istanza. Puoi fare tutto ciò che desideri per configurare quella istanza.

  • Last updated on