Inżynieria promptów i strukturyzowany wynik w .NET: OpenAI, Azure, Anthropic, Gemini

Bot obsługi klienta, który łączy się bezpośrednio z GPT-4o z kontrolera ASP.NET Core, może zapewnić możliwość przetestowania rozwiązania. Następnie klient korporacyjny prosi o przechowywanie danych w określonej regionie, dział bezpieczeństwa żąda użycia Claude do obsługi długich dokumentów, a dział finansowy chce wiedzieć, dlaczego każde z zapytań kosztuje dziesięć razy więcej niż szacowano. Każde z tych żądań skłania do wyboru innego dostawcy lub do użycia abstrakcji umożliwiającej ich wymianę.

OpenAI, Azure OpenAI, Anthropic i Gemini sprzedają to samo podstawowe rozwiązanie: zarządzany czat, możliwość wywoływania narzędzi oraz funkcje embedding bez konieczności hostowania kart graficznych GPU. Różnią się pakietowaniem, dostępnymi regionami, wymogami regulacyjnymi, jakością SDK oraz sposobem fakturowania. Dla usługi .NET, która będzie funkcjonować przez lata, te różnice są ważniejsze niż to, który model był na czele listy rankingowej w zeszłym tygodniu.

Który dostawca pasuje do jakiego zadań

• Platforma OpenAI: najszybsza droga do najnowszych modeli. Odpowiednia dla produktów, które już dobrze funkcjonują w ramach ograniczeń danych OpenAI.
• Azure OpenAI: gdy obciążenie musi być realizowane w ramach konta Azure z identyfikatorem przedsiębiorstwa, funkcjami sieciowymi oraz kontrolami regionalnymi.
• Anthropic: doskonałe radzenie sobie z długimi kontekstami oraz dokładne przestrzeganie instrukcji. Warto ją rozważyć dla agentów pracujących z dużą ilością dokumentów.
• Gemini: rozwiązania zintegrowane z Google Cloud, mocne strony w obszarze multimodalności oraz produkty blisko powiązane z Workspace.

Nie wybieraj automatycznie kilku dostawców. Przy jednym zespole, jednym regionie i braku wymogów związanych z zgodnością, jeden dostawca oznacza mniej elementów wymagających zarządzania. Każda abstrakcja wiąże się z dodatkowymi kosztami.

Dojrzałość SDK oraz pakietów do zainstalowania

To, co oceniasz, to oficjalne biblioteki klienta, idiomatyczne wzorce asynchroniczne oraz częstotliwość wprowadzania zmian zakłócających funkcjonowanie oprogramowania. SDK, które kłóci się z mechanizmem życiowym HttpClient i zasadami iniekcji zależności, będzie kosztować cię więcej niż rachunek za tokeny. Oczekuj pakietów stworzonych przez producenta lub dobrze wspieranych przez społeczność dla wszystkich czterech elementów, ale sprawdź aktualne wersje NuGet oraz metody autoryzacji (klucz API versus Entra ID), zanim cokolwiek ustandaryzujesz.

// Official OpenAI SDK
dotnet add package OpenAI

// Azure AI Foundry (Azure OpenAI)
dotnet add package Azure.AI.OpenAI

// Anthropic Claude (official, beta as of 2026)
dotnet add package Anthropic

// Gemini via Google Cloud Vertex AI (IChatClient-compatible, January 2026)
dotnet add package Google.Cloud.VertexAI.Extensions --prerelease

// Abstraction layer (ships with all provider adapters)
dotnet add package Microsoft.Extensions.AI

Microsoft.Extensions.AI jest elementem, który łączy je ze sobą: każde SDK udostępnia interfejs IChatClient, dzięki czemu reszta aplikacji może pozostać neutralna pod względem dostawcy.

Mechanizmy cenowe i kierowanie modelem

Każdy dostawca pobiera opłatę za tokeny, ale szczegóły wpływają na całkowitą kwotę: tokeny wejściowe i wyjściowe są wyceniane inaczej, tokeny z pamięci podręcznej są tańsze, narzędzia mogą generować dodatkowe opłaty, a niektóre plany wymagają minimalnych ilości. Długi kontekst oraz agenci wykorzystujące wiele narzędzi szybko zwiększają rachunek. Azure nalicza opłaty za pomocą systemu pomiarowego Azure, natomiast pozostałe trzy dostawcy naliczają opłaty na koncie dostawcy.

Dział finansowy stworzy model ekonomiki jednostkowej, dlatego twoja architektura musi dostarczać dane o zużyciu, którym będą ufali. Każde wezwanie służące do zakończenia zadania powinno być monitorowane za pomocą urządzenia pomiarowego, które rejestruje model, tokeny oraz flagi funkcjonalne. Budżety powinny być zdefiniowane w kodzie oraz w alertach dotyczących rachunków chmurowych. Najtańszym rozwiązaniem jest kierowanie zadań według ich złożoności:

// Partial example — model routing based on task complexity
public class ModelRouter
{
    // Route cheap, simple tasks to the nano model
    // Route complex multi-step reasoning to the full model
    public string SelectModel(TaskComplexity complexity) => complexity switch
    {
        TaskComplexity.Classification  => "gpt-5.4-nano",   // ~20x cheaper than full
        TaskComplexity.Conversational  => "gpt-5.4-mini",   // ~5x cheaper
        TaskComplexity.Reasoning       => "gpt-5.4",         // full capability
        _                              => "gpt-5.4-mini"
    };
}

Przystosowanie do dużych firm: tożsamość, sieć i lokalizacja

Kwestionariusze bezpieczeństwa kończą projekty, które zostały zoptymalizowane wyłącznie pod kątem opóźnień podczas demonstracji. Pytania dotyczą tożsamości, izolacji sieciowej, przechowywania danych oraz dostępności w poszczególnych regionach.

Azure OpenAI odziedzicza system Azure RBAC, funkcję Private Link oraz możliwość wyboru regionu. OpenAI i Anthropic oferują kontrole organizacyjne oraz opcje zerowego przechowywania danych, przy czym istnieją określone warunki, które należy przeczytać. Gemini follows wzorce Google Cloud IAM i VPC.

Jeśli chodzi o autoryzację w ASP.NET Core, dla Azure OpenAI należy preferować zarządzaną tożsamość. W przypadku dostawców kluczy API należy na starcie ładować tajne dane z Key Vault i rotować je bez konieczności ponownego rozpakowywania aplikacji. Nigdy nie łącz kluczy dostawcy z tokenami JWT użytkowników.

Przegląd prawny musi obejmować opcję wycofania się z wykorzystania danych do szkolenia, podwykonawców oraz sformułowania umowy DPA dla każdego aktywowanego dostawcy, a nie tylko dla głównego. Wielu dostawców oznacza wiele umów.

Strukturyzowany wynik z JSON Schema

Wsparcie dla JSON Schema oraz ograniczone dekodowanie różni się pomiędzy dostawcami. Wolno preferować usługodawców, którzy potrafią egzekwować schemat dla argumentów narzędzia oraz odpowiedzi, którym już ufają deserializatory w C#, a w przypadku słabego nadzoru korzystać z metody walidacji i ponownej próby. Z Azure OpenAI można ustawić schemat na rygorystyczny poziom:

// Full example — Azure OpenAI structured output with strict schema enforcement
using Azure.AI.OpenAI;
using OpenAI.Chat;
using System.ComponentModel;
using System.Text.Json;

// Define the schema type — only JSON Schema primitives are supported
public class SupportTicketAnalysis
{
    public string Category { get; set; } = string.Empty;        // e.g. "billing", "technical"
    public string Priority { get; set; } = string.Empty;        // "low", "medium", "high", "critical"

    [Description("One to two sentence summary of the issue")]
    public string Summary { get; set; } = string.Empty;

    public string[] RequiredTeams { get; set; } = [];           // which teams must be looped in

    [Description("Estimated resolution time as a human-readable string, e.g. '2 business days'")]
    public string EstimatedResolution { get; set; } = string.Empty;
}

// Build the client — structured outputs require API version 2024-08-01-preview or later
var azureClient = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!),
    new AzureOpenAIClientOptions(AzureOpenAIClientOptions.ServiceVersion.V2024_08_01_Preview));

ChatClient chatClient = azureClient.GetChatClient("gpt-5.4-mini-deployment");

// Configure the request to enforce the schema strictly
var options = new ChatCompletionOptions
{
    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat<SupportTicketAnalysis>(
        "support_ticket_analysis",  // snake_case — spaces and hyphens cause 400 errors
        strict: true)               // without this, schema compliance is best-effort only
};

List<ChatMessage> messages =
[
    new SystemChatMessage("You are a support ticket classifier. Analyze the ticket and return a structured assessment."),
    new UserChatMessage("User reports: 'My invoice shows $999 but the contract says $299. Need this fixed immediately.'")
];

// If structured outputs fail with a 400, the schema has unsupported types — check for DateTime, Uri, TimeSpan
ClientResult<ChatCompletion> result = await chatClient.CompleteChatAsync(messages, options);

// JsonSerializer.Deserialize will always succeed if the API call succeeded
SupportTicketAnalysis analysis = JsonSerializer.Deserialize<SupportTicketAnalysis>(
    result.Value.Content.Text)!;

Console.WriteLine(quot;Category: {analysis.Category}");
Console.WriteLine(quot;Priority: {analysis.Priority}");
Console.WriteLine(quot;Summary: {analysis.Summary}");

Dwa aspekty w tym przykładzie powodują większość błędów 400: nazwy schematów muszą być w formacie snake_case, a typy takie jak DateTime, Uri lub TimeSpan nie należą do prymitywów JSON Schema. Bez ustawienia strict: true zgodność jest realizowana jedynie w maksymalnym możliwym stopniu.

Wywoływanie narzędzi, embeddingi i RAG

Wszystkie cztery rozwiązania obsługują wywoływanie narzędzi lub funkcji, przy czym każde z nich ma inny kształt danych wejściowych. Normalizuj je do wewnętrznego DTO ToolCall na granicy, aby kod orkiestracji nie musiał się dostosowywać do poszczególnych dostawców.

Wybór dostawcy czatu nie oznacza automatycznego wyboru jego embeddingów. Określ model i wymiary embeddingów w konfiguracji i nie zmieniaj ich potajemnie przy zmianie dostawcy czatu. Agresywnie cacheuj embeddingi oraz deterministyczne wyniki narzędzi, ale nie cacheuj surowych odpowiedzi z czatu zawierających dane osobowe użytkownika, chyba że obowiązuje w tym zakresie polityka przechowywania.

Cienka abstrakcja .NET z IChatClient

Zdefiniuj małą interfejs providera z metodami strumieniowymi i niestrumieniowymi, przypisz każde SDK za pomocą adaptera i wstrzyknij je za pomocą DI. Zachowaj komunikaty i narzędzia poza adapterami. Unikaj „boskich” frameworków, które ukrywają mechanizmy ponawiania prób i czasów oczekiwania, które trzeba dostosować. Dzięki IChatClient rejestracja odczytuje providera z konfiguracji i otacza wszystko rozwiązaniem OpenTelemetry:

// Partial example — Program.cs provider registration with IChatClient
using Microsoft.Extensions.AI;
using Azure.AI.OpenAI;
using OpenAI;
using Anthropic;
using Google.Cloud.VertexAI.Extensions;

var builder = WebApplication.CreateBuilder(args);
var config = builder.Configuration;

// Read which provider to use from configuration — no code change to switch
string provider = config["AI:Provider"]!; // "azure", "openai", "anthropic", "gemini"

builder.Services.AddSingleton<IChatClient>(sp =>
{
    // Return the appropriate IChatClient implementation based on config
    return provider switch
    {
        "azure" => new AzureOpenAIClient(
                        new Uri(config["AI:Azure:Endpoint"]!),
                        new Azure.AzureKeyCredential(config["AI:Azure:Key"]!))
                    .GetChatClient(config["AI:Azure:Deployment"]!)
                    .AsIChatClient(), // extension method from Azure.AI.OpenAI

        "openai" => new OpenAIClient(config["AI:OpenAI:Key"]!)
                    .GetChatClient(config["AI:OpenAI:Model"]!)
                    .AsIChatClient(),

        "anthropic" => new AnthropicClient(config["AI:Anthropic:Key"]!)
                    .AsIChatClient(), // Anthropic SDK v10+ implements IChatClient

        "gemini" => new VertexAIChatClient(
                        projectId: config["AI:Gemini:ProjectId"]!,
                        location: config["AI:Gemini:Location"]!,
                        modelId: config["AI:Gemini:Model"]!),

        _ => throw new InvalidOperationException(quot;Unknown AI provider: {provider}")
    };
});

// Add OpenTelemetry instrumentation via pipeline decorator — applies to all providers
builder.Services.AddSingleton(sp =>
{
    var inner = sp.GetRequiredService<IChatClient>();
    return new ChatClientBuilder(inner)
        .UseOpenTelemetry(loggerFactory: sp.GetRequiredService<ILoggerFactory>(),
                          sourceName: "YourApp.AI")
        .Build();
});

Flagi funkcjonalne powinny wybierać dostawcę dla każdego użytkownika lub umiejętności. Jedyny statyczny klient zaimplementowany bezpośrednio w Program.cs sprawia, że wyjątki związane z lokalizacją przekształcają się w incydenty.

Strumieniowanie wymaga również wyraźnego kontraktu w abstrakcji: tokenów anulowania, mechanizmów backpressure oraz sposobu, w jaki częściowe wywołania narzędzi docierają do wywołujących je funkcji. Dostawcy różnią się na tyle, że „proste oczekiwanie na wynik” wprowadza semantykę konkretnego dostawcy do kontrolerów.

Działający przykład konceptu

Cała idea mieści się w małej aplikacji Web API. Uruchom projekt i dodaj odpowiednie pakiety:

dotnet new webapi -n AiProviderPoc --no-openapi
cd AiProviderPoc

dotnet add package Microsoft.Extensions.AI
dotnet add package OpenAI
dotnet add package Azure.AI.OpenAI
dotnet add package Anthropic
dotnet add package Google.Cloud.VertexAI.Extensions --prerelease

Kontrakt promptu jest udostępniany przez wszystkich dostawców. Typ wyniku musi odpowiadać prymitywom JSON Schema, a opisy służą jednocześnie jako wskazówki dla modelu:

// PromptContracts.cs — shared across all providers
using System.ComponentModel;

namespace AiProviderPoc;

// The input to every analysis request
public record AnalysisRequest(string TicketText, string? Context = null);

// The structured output — must use only JSON Schema primitives (string, int, bool, arrays)
public class TicketAnalysis
{
    [Description("Category of issue: 'billing', 'technical', 'account', 'feature-request'")]
    public string Category { get; set; } = string.Empty;

    [Description("Severity: 'low', 'medium', 'high', 'critical'")]
    public string Severity { get; set; } = string.Empty;

    [Description("One to two sentence summary of the customer's issue")]
    public string Summary { get; set; } = string.Empty;

    [Description("Suggested action for the support agent, one sentence")]
    public string SuggestedAction { get; set; } = string.Empty;

    public bool RequiresEscalation { get; set; }

    [Description("Estimated time to resolve as human-readable string, e.g. '30 minutes' or '2 business days'")]
    public string EstimatedResolution { get; set; } = string.Empty;
}

Usługa traktuje systemowy prompt jako stabilną, wersjonowaną umowę i polega wyłącznie na IChatClient. Wykorzystuje neutralny pod względem dostawcy tryb JSON; w celu ścisłego przestrzegania schematu w Azure lub OpenAI należy zastosować wcześniej opisany bezpośredni podejście z SDK.

// TicketAnalysisService.cs
using Microsoft.Extensions.AI;
using System.Text.Json;

namespace AiProviderPoc;

public class TicketAnalysisService(IChatClient chatClient)
{
    // The system prompt is the stable contract — versioned and centralized here
    private const string SystemPrompt =
        """
        You are a support ticket classifier for an enterprise software product.
        Analyze the provided support ticket and return a structured assessment.
        Be concise and accurate. Do not invent information not present in the ticket.
        """;

    public async Task<TicketAnalysis> AnalyzeAsync(AnalysisRequest request, CancellationToken ct = default)
    {
        // Build the message list — system prompt is fixed, user content is the ticket
        var messages = new List<ChatMessage>
        {
            new(ChatRole.System, SystemPrompt),
            new(ChatRole.User, request.TicketText)
        };

        // Use JSON mode via ChatOptions — provider-agnostic structured output
        // For strict schema enforcement with Azure/OpenAI, use the SDK-direct approach instead
        var options = new ChatOptions
        {
            ResponseFormat = ChatResponseFormat.Json
        };

        ChatResponse response = await chatClient.GetResponseAsync(messages, options, ct);

        // Deserialize — IChatClient normalizes the response shape across all providers
        return JsonSerializer.Deserialize<TicketAnalysis>(response.Text,
            new JsonSerializerOptions { PropertyNameCaseInsensitive = true })
            ?? throw new InvalidOperationException("Model returned unparseable JSON");
    }
}

Program.cs rejestruje jednego klienta na każdą gałąź dostawcy i udostępnia jeden koniec punktu końcowego, który nigdy nie dowiaduje się, który dostawca odpowiedział:

using AiProviderPoc.Api;
using Anthropic;
using Azure.AI.OpenAI;
using Google.GenAI;
using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;          // ApiKeyCredential

var builder = WebApplication.CreateBuilder(args);
var config = builder.Configuration;

// Read provider selection from config — change "AI:Provider" to switch providers
string provider = config["AI:Provider"]
    ?? throw new InvalidOperationException("AI:Provider must be set in appsettings");

// Register IChatClient — each branch returns a different SDK's implementation
builder.Services.AddSingleton<IChatClient>(_ =>
{
    return provider.ToLowerInvariant() switch
    {
        "azure" =>
            // Azure AI Foundry: needs endpoint + key + deployment name
            new AzureOpenAIClient(
                new Uri(config["AI:Azure:Endpoint"]!),
                new ApiKeyCredential(config["AI:Azure:Key"]!))
            .GetChatClient(config["AI:Azure:Deployment"]!)
            .AsIChatClient(),

        "openai" =>
            // OpenAI direct: needs API key + model name
            new OpenAIClient(config["AI:OpenAI:Key"]!)
            .GetChatClient(config["AI:OpenAI:Model"]!)
            .AsIChatClient(),

        "anthropic" =>
            // AnthropicClient expects a ClientOptions instance (not a string API key).
            // Create a ClientOptions and pass it to the constructor.
            new AnthropicClient(
                new Anthropic.Core.ClientOptions
                {
                    ApiKey = config["AI:Anthropic:Key"]!
                })
            .AsIChatClient(),

        "gemini" =>
            // Google.GenAI: named params on Client constructor, no ClientConfig class needed.
            // Uses GOOGLE_APPLICATION_CREDENTIALS / ADC for auth; no API key required for Vertex AI.
            new Client(
                project: config["AI:Gemini:ProjectId"]!,
                location: config["AI:Gemini:Location"]!,
                vertexAI: true)
            .AsIChatClient(config["AI:Gemini:Model"]!),

        _ => throw new InvalidOperationException(quot;Unknown provider: '{provider}'. Valid: azure, openai, anthropic, gemini")
    };
});

// Register the service — depends only on IChatClient
builder.Services.AddScoped<TicketAnalysisService>();

var app = builder.Build();

// Single endpoint — provider is invisible here
app.MapPost("/analyze", async (AnalysisRequest request, TicketAnalysisService service, CancellationToken ct) =>
{
    var analysis = await service.AnalyzeAsync(request, ct);
    return Results.Ok(analysis);
});

app.Run();

Zmiana dostawcy polega na modyfikacji konfiguracji w pliku appsettings.json:

{
  "AI": {
    "Provider": "azure",
    "Azure": {
      "Endpoint": "https://your-resource.openai.azure.com/",
      "Key": "your-azure-key",
      "Deployment": "gpt-5.4-mini-deployment"
    },
    "OpenAI": {
      "Key": "sk-...",
      "Model": "gpt-4o-mini"
    },
    "Anthropic": {
      "Key": "sk-ant-..."
    },
    "Gemini": {
      "ProjectId": "your-gcp-project",
      "Location": "us-central1",
      "Model": "gemini-2.0-flash"
    }
  }
}

Zainstaluj to i utwórz zgłoszenie:

dotnet run

curl -X POST http://localhost:5000/analyze \
  -H "Content-Type: application/json" \
  -d '{"ticketText": "My subscription renews tomorrow but I was charged twice this month. Account #A-1234."}'

Odpowiedź wraca w tym samym formacie, niezależnie od tego, który dostawca jest skonfigurowany:

{
  "category": "billing",
  "severity": "high",
  "summary": "Customer was charged twice for their subscription and is seeking a refund before their next renewal date.",
  "suggestedAction": "Review billing history for account A-1234 and initiate a refund for the duplicate charge.",
  "requiresEscalation": false,
  "estimatedResolution": "1 business day"
}

Inżynieria promptów, oceny i sprawiedliwe porównania

Gdy porównujesz jakość, utrzymaj niezmienne prompty oraz parametry temperatury, zmieniając jedynie dostawcę i model. W przeciwnym razie porównujesz raczej szczęście związanе z inżynierią promptów niż same dostawcze rozwiązania. Zachowuj wersjonowanie szablonów promptów i przeprowadzaj testy A/B niezależnie od adaptera dostawcy, ponieważ każda zmiana modelu unieważnia twoje eksperymenty z promptami.

Wytwarzaj dane OpenTelemetry dotyczące wywołań dostawcy, zawierające informacje o dostawcy, modelu, liczbie tokenów oraz powodzie zakończenia jako atrybuty. Połącz te metryki online z zestawami ocen offline, aby wybór tańszego modelu był decyzją opartą na dowodach, a nie na nadziei.

Różnią się również budżety opóźnień. Niektórzy dostawcy przesyłają pierwszy token szybciej, inni radzą sobie lepiej przy dłuższych procesach generowania treści. Zmierz zarówno czas do otrzymania pierwszego tokenu, jak i czas od początku do końca dla swojego obciążenia pracy, zanim wybierzesz standardowe ustawienia.

Uruchamianie więcej niż jednego dostawcy w produkcji

• Canary: zachowaj jeden „golden prompt” na każde środowisko, który gwarantuje poprawność JSON zgodną ze schematem oraz określa wartość SLO dotyczącą opóźnienia, oraz odrzuca deplojacje, które naruszają te wymagania w przypadku głównego dostawcy.
• Filtrzy treści: filtry treści Azure oraz inne mechanizmy bezpieczeństwa zwracają różne formaty błędów. Przypisz je raz do wyjątków w swoim domenie.
• Przełączenie awaryjne: zdecyduj, które błędy można spróbować naprawić w przypadku drugiego dostawcy, a które muszą zostać natychmiast odrzucone, takie jak błędy autoryzacji czy odrzucenia zgodnie z polityką. Bezrefleksyjne przełączenie awaryjne może złamać obietnice dotyczące lokalizacji danych.
• Osoby na dyżurze: przeszkol ludzi w zakresie paneli rozliczeniowych każdego włączonego dostawcy. Lepsze jest szybkie zatrzymanie nagłego wzrostu aktywności o 2 w nocy, gdy instrukcje wskazują dokładną nazwę interfejsu.
• Wycofywanie z użycia: wyłącz klucze, usuń rejestracje aplikacji, usuń zestawy danych do testów zawierające tekst klientów oraz przechowaj raporty kosztowe w archiwum.

Szybka lista kontrolna decyzji

Czy wymagana jest lokalizacja serwerów? Zacznij od Azure OpenAI. Długie dokumenty? Sprawdź Anthropic. Jesteś już na GCP? Ocenić Gemini. Potrzebujesz najnowszych modeli OpenAI w dniu ich udostępnienia? Użyj platformy OpenAI. Potrzebujesz dwóch z powyższych rozwiązań? Najpierw stwórz lekki adapter oraz system pomiaru zużycia.

Wybór dostawcy to decyzja związana z architekturą przedsiębiorstwa, która ma konsekwencje pod względem SDK i kosztów. Porównaj kryteria takie jak lokalizacja serwerów, zarządzanie tożsamościami, przejrzystość cen, strukturyzowany wynik oraz dopasowanie do potrzeb operacyjnych.