Partager via

Accéder aux données dans les fonctions IA

Lorsque vous créez des fonctions IA, vous devrez peut-être accéder aux données contextuelles au-delà des paramètres fournis par le modèle IA. La Microsoft.Extensions.AI bibliothèque fournit plusieurs mécanismes pour transmettre des données aux délégués de fonction.

Classe AIFunction

Le AIFunction type représente une fonction qui peut être décrite dans un service IA et appelée. Vous pouvez créer des AIFunction objets en appelant l'une des AIFunctionFactory.Create surcharges. Mais AIFunction est également une classe de base, et vous pouvez dériver de celui-ci et implémenter votre propre type de fonction IA. DelegatingAIFunction offre un moyen simple d'encapsuler un AIFunction existant et d'y ajouter des fonctionnalités supplémentaires, y compris la capture de données additionnelles à utiliser.

Transmettre des données

Vous pouvez associer des données à la fonction au moment de sa création, via la fermeture ou via AdditionalProperties. Si vous créez votre propre fonction, vous pouvez remplir AdditionalProperties ce que vous souhaitez. Si vous utilisez AIFunctionFactory pour créer la fonction, vous pouvez remplir des données à l’aide de AIFunctionFactoryOptions.AdditionalProperties.

Le délégué fourni à AIFunctionFactory vous permet également de capturer toutes les références aux données. C’est-à-dire, vous pouvez intégrer tout ce que vous voulez référencer dans AIFunction elle-même.

Accéder aux données dans les délégués de fonctions

Vous pouvez appeler votre AIFunction directement, ou vous pouvez l’appeler indirectement en utilisant FunctionInvokingChatClient. Les sections suivantes décrivent comment accéder aux données d’argument à l’aide de l’une ou l’autre approche.

Appel de fonction manuelle

Si vous appelez manuellement un AIFunction en utilisant AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken), vous transmettez AIFunctionArguments. Le AIFunctionArguments type inclut :

Si vous souhaitez accéder soit à AIFunctionArguments soit à IServiceProvider dans votre délégué AIFunctionFactory.Create, créez un paramètre typé comme IServiceProvider ou AIFunctionArguments. Ce paramètre sera lié aux données pertinentes du AIFunctionArguments passé à AIFunction.InvokeAsync().

Le code suivant montre un exemple :

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 est également géré de manière spéciale : si le délégué ou lambda a un paramètre CancellationToken, il sera lié à celui CancellationToken qui a été passé à AIFunction.InvokeAsync().

Appel via FunctionInvokingChatClient

FunctionInvokingChatClient publie l'état concernant l'invocation actuelle vers FunctionInvokingChatClient.CurrentContext, y compris non seulement les arguments, mais aussi tous les objets d'entrée ChatMessage, le ChatOptions, et les détails sur la fonction appelée (parmi combien). Vous pouvez ajouter les données que vous souhaitez dans ChatOptions.AdditionalProperties et les extraire à l'intérieur de votre AIFunction depuis FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties.

Le code suivant montre un exemple :

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

Injection de dépendances

Si vous utilisez FunctionInvokingChatClient pour appeler automatiquement des fonctions, ce client configure un AIFunctionArguments objet qu’il passe dans le AIFunction. Comme AIFunctionArguments inclut le IServiceProvider que le FunctionInvokingChatClient avait lui-même fourni, si vous construisez votre client à l'aide des moyens DI standard, ce IServiceProvider est transmis jusqu'à votre AIFunction. À ce stade, vous pouvez l'interroger pour tout ce que vous voulez à partir du DI.

Techniques avancées

Si vous souhaitez un contrôle plus précis sur la façon dont les paramètres sont liés, vous pouvez utiliser AIFunctionFactoryOptions.ConfigureParameterBinding, ce qui vous permet de contrôler la façon dont chaque paramètre est rempli. Par exemple, le SDK C# MCP utilise cette technique pour lier automatiquement des paramètres à partir de l’API.

Si vous utilisez la AIFunctionFactory.Create(MethodInfo, Func<AIFunctionArguments,Object>, AIFunctionFactoryOptions) surcharge, vous pouvez également exécuter votre propre logique arbitraire lorsque vous créez l’objet cible sur lequel la méthode d’instance sera appelée, chaque fois. Et vous pouvez faire ce que vous souhaitez pour configurer cette instance.

  • Last updated on