Auswählen eines Endpunkts und SDK

  • 7 Minuten

Microsoft Foundry bietet Flexibilität beim Entwickeln von generativen KI-Chatanwendungen. Bevor Sie mit der Entwicklung beginnen, ist es wichtig, die verfügbaren Optionen zu verstehen und zu entscheiden, welche dieser Optionen verwendet werden sollen. Einige Überlegungen zum Entwickeln einer Anwendung umfassen:

  • Endpunkte: Microsoft Foundry-Projekte stellen zwei Endpunkte bereit, mit denen Sie eine Verbindung mit Projektressourcen herstellen und nutzen können, z. B. Modellbereitstellungen, aus Clientanwendungen. Jedes Projekt verfügt sowohl über einen Project-Endpunkt als auch über einen Azure OpenAI-Endpunkt.
  • Client-SDK: Je nach ausgewähltem Endpunkt können Sie das Microsoft Foundry SDK oder das OpenAI SDK verwenden, um eine generative KI-Chatanwendung zu entwickeln. Beide SDKs unterstützen ein openAI-API-kompatibles Clientobjekt, das Aufforderungen an Modelle übermitteln kann, aber es gibt einige Unterschiede in den spezifischen Funktionen, die in jedem SDK verfügbar sind.
  • Authentifizierung: Je nach Endpunkt und SDK, den Sie verwenden möchten, gibt es mehrere Möglichkeiten, wie eine Clientanwendung von Foundry authentifiziert werden kann, um Zugriff auf Ressourcen zu erhalten. Im Allgemeinen sollten Produktionsanwendungen die Microsoft Entra ID-Authentifizierung verwenden, die erfordert, dass die Anwendung im Kontext einer bestimmten Identität ausgeführt wird; in einigen Szenarien können Sie aber auch die schlüsselbasierte oder tokenbasierte Authentifizierung verwenden.
  • Chat-API: Die OpenAI-Client-API unterstützt zwei Chat-APIs: ChatCompletions und Antworten. Während die Antwort-API für die meisten neuen Entwicklungsprojekte empfohlen wird, ist die ChatCompletions-API über viele generative KI-Modelle und -Plattformen hinweg gut etabliert und kompatibel.

Beginnen wir mit der Betrachtung der verfügbaren Endpunkte, Client-SDKs und Authentifizierungsmethoden – wir werden die ApIs für Antworten und ChatCompletions später untersuchen.

Verwenden des Foundry SDK mit dem Projektendpunkt

Das Microsoft Foundry SDK bietet programmgesteuerten Zugriff auf Ressourcen in Ihren Projekten über eine REST-API und sprachspezifische Clientbibliotheken; Einschließlich:

Hinweis

In diesem Modul werden Python-Codebeispiele für allgemeine Aufgaben verwendet. Sie können auf die sprachspezifische SDK-Dokumentation für gleichwertigen Code in Ihrer bevorzugten Sprache verweisen. Jedes SDK wird unabhängig entwickelt und verwaltet, sodass sich einige Funktionen möglicherweise in verschiedenen Phasen der Implementierung befinden.

Installieren des SDK

Um die Bibliothek Azure KI-Projekte in Python zu verwenden, installieren Sie das paket azure-ai-projects aus PyPI zusammen mit unterstützenden Paketen:

pip install azure-ai-projects azure-identity openai

Hinweis

Wenn Sie das Foundry SDK zum Entwickeln einer Chatanwendung verwenden, müssen Sie auch das OpenAI SDK-Paket importieren – die Chatclientfunktionalität im Foundry SDK wird vom OpenAI SDK abgeleitet.

Herstellen einer Verbindung mit dem Projektendpunkt

Jede Foundry-project verfügt über einen eindeutigen Endpunkt, den Sie auf der Seite project Overview im Foundry-Portal unter https://ai.azure.com finden können.

Der Projektendpunkt folgt diesem Format:

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

Verwenden Sie diesen Endpunkt, um ein AIProjectClient-Objekt zu erstellen:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

Hinweis

Der Code verwendet zum Authentifizieren standardmäßige Azure Anmeldeinformationen. Um diese Authentifizierung zu aktivieren, müssen Sie das Paket azure-identity installieren (siehe oben im Installationsbefehl).

Tipp

Um erfolgreich auf das Projekt zuzugreifen, muss der Code in einer authentifizierten Azure-Sitzung ausgeführt werden. Sie können z. B. den Befehl Azure CLI az login verwenden, um sich anzumelden, bevor Sie den Code ausführen.

Der Projektclient (AIProjectClient) bietet Zugriff auf Foundry-native Vorgänge, die keine OpenAI-Entsprechungen besitzen. Verwenden Sie den project-Client, um:

  • Abrufen von Ressourcenverbindungen
  • Access-Projektkonfiguration
  • Aktivieren der Ablaufverfolgung
  • Verwalten von Datasets und Indizes

Erstellen eines Chatclients

Um mit einem Modell in Ihrem Foundry-Projekt zu chatten, benötigen Sie ein openAI-kompatibles Clientobjekt. Sie können die get_openai_client()- Methode des Projektclients verwenden, um eine wie folgt abzurufen:

openai_client = project_client.get_openai_client(api_version="2024-10-21")

Sie können dann dieses Chatclientobjekt verwenden, um Aufforderungen an Modelle zu senden und Antworten zurückzugeben.

Verwenden des OpenAI SDK mit dem Azure OpenAI-Endpunkt

Das OpenAI SDK ist die offizielle Clientbibliothek zum Aufrufen der OpenAI-API. Er verarbeitet HTTP-Anforderungen, Authentifizierung, Wiederholungen und Antwortanalyse. Das SDK funktioniert mit openAI-gehosteten Modellen, Azure OpenAI-Bereitstellungen und Foundry-Modellen mit denselben Mustern.

Installieren des SDK

Um die OpenAI-Bibliothek in Python zu verwenden, installieren Sie das Openai-Paket von PyPI zusammen mit unterstützenden Paketen:

pip install openai azure-identity

Hinweis

Das Azure-Identity-Paket ist erforderlich, wenn Sie die tokenbasierte Authentifizierung verwenden möchten, um mithilfe von Microsoft Entra ID-Anmeldeinformationen eine Verbindung mit dem Endpunkt herzustellen.

Herstellen einer Verbindung mit dem Azure OpenAI-Endpunkt

Jedes Foundry-Projekt enthält einen Azure OpenAI-Endpunkt, den Sie auf der Seite "Übersicht" des Projekts im Foundry-Portal unter finden https://ai.azure.com.

Der Azure OpenAI-Endpunkt folgt diesem Format:

https://{resource-name}.openai.azure.com/openai/v1

Erstellen Sie einen OpenAI-Client mit Ihren Endpunkt- und Azure-Anmeldeinformationen:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Zusätzlich zur Microsoft Entra-ID (empfohlen) können Sie sich mit einem API-Schlüssel oder Umgebungsvariablen authentifizieren.

API-Schlüsselauthentifizierung:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Von Bedeutung

Verwenden Sie API-Schlüssel mit Vorsicht. Speichern Sie sie sicher in Azure Key Vault, und fügen Sie sie niemals direkt in Ihren Code ein.

Umgebungsvariablen:

Wenn Sie die Umgebungsvariablen OPENAI_BASE_URL und OPENAI_API_KEY festlegen, verwendet der Client diese automatisch:

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Unabhängig davon, wie Sie sich für die Authentifizierung entscheiden, verarbeitet der OpenAI-Client Modell-Ableitungsvorgänge. Verwenden Sie sie für:

  • Generieren von Antworten mit der Antwort-API
  • Chatabschluss und Bildgenerierung
  • Zugriff auf Foundry-Direktmodelle (nicht-Azure OpenAI-Modelle)

Verwenden eines AzureOpenAI-Clientobjekts

Im Allgemeinen sollten Sie das OpenAI-Clientobjekt verwenden, um mit Modellen über den Azure OpenAI v1-Endpunkt zu chatten. Sie haben jedoch auch die Möglichkeit, ein AzureOpenAI-Clientobjekt zu erstellen, wenn Sie Funktionen aus einer bestimmten Version der Azure OpenAI-API verwenden müssen. Um ein AzureOpenAI-Clientobjekt zu erstellen, müssen Sie die API-Version und den Azure-Endpunkt wie folgt angeben:

import os
from openai import AzureOpenAI
    
openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Auswählen zwischen dem Foundry SDK und dem OpenAI SDK

Microsoft Foundry unterstützt zwei Ansätze zum Erstellen von KI-Anwendungen. Jeder dient verschiedenen Zwecken und dem Verständnis, wann jeder verwendet werden soll, hilft Ihnen, die richtige Lösung zu erstellen.

Wann das Foundry SDK verwendet werden soll

Verwenden Sie das Foundry SDK, wenn Ihre Anwendung Foundry-spezifische Funktionen benötigt:

  • Foundry Agent Service zum Erstellen und Verwalten von KI-Agents
  • Toolaufrufe und Genehmigungsworkflows
  • Cloud-Auswertungen zum Testen und Validieren von KI-Antworten
  • Ablaufverfolgung und Observierbarkeit für die Überwachung des Anwendungsverhaltens
  • Direkte Foundry-Modelle (Nicht-Azure OpenAI-Modelle, die über den Modellkatalog verfügbar sind)
  • Projekt-Metadaten, -Verbindungen und -Governancefunktionen

Microsoft empfiehlt das Foundry SDK beim Erstellen von Apps mit Agents, Evaluierungen oder Foundry-spezifischen Features.

Wann das OpenAI SDK verwendet werden soll

Verwenden Sie das OpenAI SDK, wenn Sie maximale Kompatibilität mit der OpenAI-API benötigen:

  • Vollständige OpenAI-API-Kompatibilität für vorhandenen Code und Tools
  • Portabilität zwischen OpenAI- und Azure OpenAI-Bereitstellungen
  • Chat-Abschluss, Antworten und Bilder APIs
  • Minimale Abhängigkeit von Gießerei-spezifischen Konzepten

Das OpenAI SDK eignet sich ideal für Modellinference-Workloads, bei denen vorhandene OpenAI-Code mit minimalen Änderungen arbeiten soll. Dieser Ansatz bietet jedoch keine Foundry-spezifischen Features wie Agents oder Auswertungen.

Microsoft Foundry bietet Ihnen Flexibilität beim Erstellen von KI-Anwendungen. Verwenden Sie das Foundry SDK mit AIProjectClient , wenn Sie Funktionen auf Projektebene wie Agenten, Auswertungen, Tracing und Verbindungen benötigen. Verwenden Sie das OpenAI SDK, wenn Sie eine einfache Modellausleitung mit maximaler OpenAI-Kompatibilität benötigen. Beide SDKs arbeiten mit Ihrem Foundry-Projektendpunkt zusammen, sodass Sie sie nach Bedarf in Ihren Anwendungen kombinieren können. Sie können beide SDKs auch in derselben Anwendung verwenden– das Foundry SDK für Projektfeatures und das OpenAI SDK für Modellinference.