Aspire OpenAI integration (förhandsversion)

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

OpenAI ger åtkomst till chatt-/slutföranden, inbäddningar, bild- och ljudmodeller via ett REST API. Med integreringen AspireOpenAI kan du:

• Modellera ett OpenAI konto (slutpunkt + API-nyckel) en gång i AppHost.
• Lägg till en eller flera modellresurser som skriver sina anslutningssträngar från den överordnade.
• Referera till dessa modellresurser från projekt för att få starkt namngivna anslutningssträngar.
• Använd dessa anslutningssträngar med komponenten Aspire.OpenAI för att hämta en OpenAIClient och (valfritt) en IChatClient.

Integrering av värdtjänster

Värdintegreringsmodellerna OpenAI inkluderar två resurstyper.

• OpenAIResource: Överordnad som innehåller den delade API-nyckeln och basslutpunkten (standardvärdet är https://api.openai.com/v1).
• OpenAIModelResource: Underordnad som representerar en specifik modell; sammansätter en anslutningssträng från den överordnade (Endpoint + Key + Model).

Om du vill komma åt dessa typer och API:er för att uttrycka dem inom ditt AppHost-projekt installerar du 📦Aspire.Hosting.OpenAI NuGet-paketet:

dotnet add package Aspire.Hosting.OpenAI

<PackageReference Include="Aspire.Hosting.OpenAI"
                  Version="*" />

Mer information finns i dotnet lägg till paket eller Hantera paketberoenden i .NET applikationer.

Lägga till en OpenAI överordnad resurs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

Lägga till OpenAI modellresurser

Lägg till en eller flera modellbarn till den överordnade modellen och referera till dem från projekt.

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

var chat = openai.AddModel("chat", "gpt-4o-mini");
var embeddings = openai.AddModel("embeddings", "text-embedding-3-small");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(chat);

// After adding all resources, run the app...

Referensen chat skickar en anslutningssträng med namnet chat till projektet. Flera modeller kan dela den enskilda API-nyckeln och slutpunkten via den överordnade resursen.

Använda standard-API-nyckelparametern

Anrop AddOpenAI("openai") skapar en hemlig parameter med namnet openai-openai-apikey. Aspire fastställer sitt värde i den här ordningen:

1. Konfigurationsnyckeln Parameters:openai-openai-apikey (användarhemligheter, appsettings.*eller miljövariabler).
2. Miljövariabeln OPENAI_API_KEY.

Om ingen av källorna ger ett värde genererar start en MissingParameterValueException. Ange ett av värdena för att undvika undantaget.

Ange nyckeln via användarhemligheter:

dotnet user-secrets set Parameters:openai-openai-apikey sk-your-api-key

Använda anpassad API-nyckelparameter

Ersätt standardparametern genom att skapa en egen hemlig parameter och anropa WithApiKey den överordnade parametern:

var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("my-api-key", secret: true);

var openai = builder.AddOpenAI("openai")
                    .WithApiKey(apiKey);

var chat = openai.AddModel("chat", "gpt-4o-mini");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(chat);

// After adding all resources, run the app...

Den ursprungliga genererade parametern tas bort från resursdiagrammet när den ersätts. Anpassade parametrar måste markeras secret: true.

Lägga till en anpassad slutpunkt

Åsidosätt standardslutpunkten (till exempel för att använda en proxy eller kompatibel gateway):

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai")
                    .WithEndpoint("https://my-gateway.example.com/v1");

var chat = openai.AddModel("chat", "gpt-4o-mini");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(chat);

// After adding all resources, run the app...

Anslutningssträngar för både huvud- och modellanslutningar inkluderar den anpassade slutpunkten.

Hälsokontroller

Lägg till en valfri engångshälsokontroll per modell för att diagnostisera problem:

var chat = builder.AddOpenAI("openai")
                  .AddModel("chat", "gpt-4o-mini")
                  .WithHealthCheck();

Modellens hälsokontroll validerar slutpunkts nåbarhet, API-nyckel giltighet (401) och modellexistens (404). Den körs bara en gång per programinstans för att begränsa hastighetsbegränsningens konsekvenser. En statussideskontroll mot https://status.openai.com/api/v2/status.json registreras automatiskt för varje överordnad resurs.

Tillgängliga modeller

Vanliga identifierare:

• gpt-5
• gpt-4o-mini
• gpt-4o
• gpt-4-turbo
• gpt-realtime
• text-embedding-3-small
• text-embedding-3-large
• dall-e-3
• whisper-1

Mer information finns i dokumentationen omOpenAI modeller.

Client integration

Kom igång med klientintegrering genom AspireOpenAI att 📦Aspireinstallera .OpenAI NuGet-paketet i det klientkrävande projektet, dvs. projektet för det program som använder OpenAI klienten.

dotnet add package Aspire.OpenAI

<PackageReference Include="Aspire.OpenAI"
                  Version="*" />

Lägga till en OpenAI klient

I den Program.cs filen för ditt klientkrävande projekt använder du AddOpenAIClient för att registrera en OpenAIClient för beroendeinmatning (DI). Metoden AddOpenAIClient kräver en parameter för anslutningsnamn.

builder.AddOpenAIClient(connectionName: "chat");

När du har lagt till OpenAIClientkan du hämta klientinstansen med hjälp av beroendeinjektion.

public class ExampleService(OpenAIClient client)
{
    // Use client...
}

Lägga till OpenAI klient med registrerad IChatClient

builder.AddOpenAIClient("chat")
       .AddChatClient(); // Model inferred from connection string (Model=...)

Om endast en överordnad resurs har definierats (ingen underordnad modell) anger du modellnamnet explicit:

builder.AddOpenAIClient("openai")
       .AddChatClient("gpt-4o-mini");

AddChatClient accepterar valfritt ett modell-/distributionsnamn; om det utelämnas kommer det från anslutningssträngen Model inlägg. Injicera OpenAIClient eller IChatClient efter behov.

Konfiguration

Aspire OpenAI-biblioteket innehåller flera alternativ för att konfigurera OpenAI-anslutningen baserat på kraven och konventionerna i ditt projekt. Antingen måste en Endpoint eller en ConnectionString anges.

Använda en anslutningssträng

Lösta anslutningssträngsformer:

Överordnad (ingen modell):

Endpoint={endpoint};Key={api_key}

Modellbarn

Endpoint={endpoint};Key={api_key};Model={model_name}

Använda konfigurationsprovidrar

Konfigurera via Aspire:OpenAI nycklar (globalt) och Aspire:OpenAI:{connectionName} (per namngiven klient). Inställningarna som stöds är Key, Endpoint, DisableTracing, DisableMetrics och underträdet ClientOptions (UserAgentApplicationId, OrganizationId, ProjectId, NetworkTimeout, loggningsalternativ osv.).

{
  "ConnectionStrings": {
    "chat": "Endpoint=https://api.openai.com/v1;Key=${OPENAI_API_KEY};Model=gpt-4o-mini"
  },
  "Aspire": {
    "OpenAI": {
      "DisableTracing": false,
      "DisableMetrics": false,
      "ClientOptions": {
        "UserAgentApplicationId": "myapp",
        "NetworkTimeout": "00:00:30"
      }
    }
  }
}

In-line-konfiguration:

builder.AddOpenAIClient("chat", settings => settings.DisableTracing = true);
builder.AddOpenAIClient("chat", configureOptions: o => o.NetworkTimeout = TimeSpan.FromSeconds(30));

Telemetri (spårningar + mått) är experimentella i SDK:t OpenAI.NET . Aktivera globalt via AppContext-växeln OpenAI.Experimental.EnableOpenTelemetry eller OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY=true. Använd DisableTracing / DisableMetrics för att avregistrera dig när det är aktiverat.

Exempelprogram

Utforska helhetsprovet som kopplar ihop värd- och klientintegreringar, ställer in API-nyckeln via parameter, registrerar en chattklient och utför en enkel dialog. Klona lagringsplatsen, kör den och anpassa den sedan för dina modeller: https://github.com/dotnet/aspire/tree/main/playground/OpenAIEndToEnd.

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Konfiguration .

Loggning / Skogsavverkning

• OpenAI.*

Spårning

• OpenAI.* (när telemetri är aktiverat och inte inaktiverat)

Metrics

• OpenAI.* mätinstrument (när telemetri är påslaget och inte avstängt)

Se även

• OpenAI dokumentation
• OpenAI .NET SDK
• Aspire översikt över integreringar
• Aspire GitHub Modellintegrering