Yapay zeka işlevlerindeki verilere erişme

Yapay zeka işlevleri oluşturduğunuzda, yapay zeka modeli tarafından sağlanan parametrelerin ötesinde bağlamsal verilere erişmeniz gerekebilir. Kütüphane, Microsoft.Extensions.AI işlev temsilcilerine veri geçirmek için çeşitli mekanizmalar sağlar.

AIFunction sınıfı

türü AIFunction , bir yapay zeka hizmetine açıklanabilen ve çağrılabilen bir işlevi temsil eder. AIFunction aşırı yüklemelerinden birini çağırarak AIFunctionFactory.Create nesneler oluşturabilirsiniz. Ancak AIFunction aynı zamanda bir temel sınıftır ve bu sınıftan türetebilir ve kendi yapay zeka işlev türünüzü uygulayabilirsiniz. DelegatingAIFunction , kullanılacak ek verileri yakalama da dahil olmak üzere mevcut AIFunction ve katmanı ek işlevlerde sarmalamanın kolay bir yolunu sağlar.

Veri aktarımı

Verileri, oluşturulma anında işlevle ilişkilendirmek için closure kavramını veya AdditionalProperties kullanabilirsiniz. Kendi işlevinizi oluşturuyorsanız, istediğiniz şekilde doldurabilirsiniz AdditionalProperties . Eğer AIFunctionFactory kullanarak işlevi oluşturursanız, AIFunctionFactoryOptions.AdditionalProperties ile verileri doldurabilirsiniz.

Ayrıca, AIFunctionFactory için sağlanan temsilcinin bir parçası olarak veri referanslarını da yakalayabilirsiniz. Bu nedenle, AIFunction'in bir parçası olarak referans almak istediğiniz her şeyi entegre edebilirsiniz.

İşlev temsilcilerindeki verilere erişme

AIFunction'yi doğrudan veya FunctionInvokingChatClient kullanarak dolaylı olarak çağırabilirsiniz. Aşağıdaki bölümlerde, iki yaklaşımdan birini kullanarak bağımsız değişken verilerine erişme işlemi açıklanmaktadır.

El ile işlev çağırma

Bir AIFunction öğesini AIFunction.InvokeAsync(AIFunctionArguments, CancellationToken) çağırarak el ile çağırırsanız, AIFunctionArguments ile geçirirsiniz. Türü AIFunctionArguments şunları içerir:

• Adlandırılmış bağımsız değişkenlerin sözlüğü.
• Context: İşleve ek ortam verileri geçirmek için isteğe bağlı IDictionary<object, object>.
• Services: IServiceProvider'un rastgele durumunu bir bağımlılık AIFunction kapsayıcısından çözümlemeye olanak tanıyan .

tr-TR: Eğer temsilciniz AIFunctionArguments içinde IServiceProvider veya AIFunctionFactory.Create öğesine erişmek istiyorsanız, IServiceProvider veya AIFunctionArguments olarak yazılan bir parametre oluşturun. Bu parametre, AIFunctionArguments ile AIFunction.InvokeAsync()'e aktarılan ilgili verilere bağlanacaktır.

Aşağıdaki kodda bir örnek gösterilmektedir:

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 ayrıca özel bir duruma sahiptir: Eğer temsilci veya lambda, bir AIFunctionFactory.CreateCancellationToken parametresine sahipse, CancellationToken'e geçirilen AIFunction.InvokeAsync() ile bağlanır.

FunctionInvokingChatClient aracılığıyla çağrı

FunctionInvokingChatClient, yalnızca bağımsız değişkenlerle değil, aynı zamanda giriş FunctionInvokingChatClient.CurrentContext nesnelerinin tümü, ChatMessage, ve kaç fonksiyondan hangisinin çağrıldığını da dahil ederek geçerli çağrıyla ilgili durumu yayımlar. Herhangi bir veriyi ChatOptions.AdditionalProperties içine ekleyebilir ve AIFunction içindeki FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties'den ayıklayabilirsiniz.

Aşağıdaki kodda bir örnek gösterilmektedir:

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

Bağımlılık enjeksiyonu

İşlevleri otomatik olarak çağırmak için FunctionInvokingChatClient kullanırsanız, istemci AIFunctionArguments içine aktardığı AIFunction nesnesini yapılandırır. İstemcinizi standart DI yöntemlerini kullanarak oluşturduğunuzda, AIFunctionArguments kendisine sağlanan IServiceProvider öğesini içerdiğinden, bu FunctionInvokingChatClient tamamen sizin IServiceProvider içerisine aktarılır. Bu noktada DI'den istediğiniz her şeyi sorgulayabilirsiniz.

İleri teknikler

Parametrelerin nasıl bağlandığı üzerinde daha ayrıntılı denetim istiyorsanız, kullanabilirsiniz AIFunctionFactoryOptions.ConfigureParameterBinding. Bu, her parametrenin nasıl doldurulabileceği konusunda sizi kontrol altına alır. Örneğin , MCP C# SDK'sı bu tekniği kullanarak DI'den parametreleri otomatik olarak bağlar.

Aşırı yüklemeyi kullanırsanız AIFunctionFactory.Create(MethodInfo, Func<AIFunctionArguments,Object>, AIFunctionFactoryOptions) , her seferinde örnek yönteminin çağrılacağı hedef nesneyi oluşturduğunuzda kendi rastgele mantığınızı da çalıştırabilirsiniz. Ayrıca bu örneği yapılandırmak için ne isterseniz yapabilirsiniz.