Choisir un point de terminaison et un Kit de développement logiciel (SDK)
Microsoft Foundry offre une flexibilité pour le développement d’applications de conversation IA génératives. Avant de commencer le développement, il est important de comprendre les options disponibles et de déterminer quelles options utiliser. Voici quelques considérations à prendre en compte pour le développement d’une application :
- Points de terminaison : les projets Microsoft Foundry fournissent deux points de terminaison que vous pouvez utiliser pour vous connecter aux ressources de projet et les consommer, telles que les déploiements de modèles, à partir d’applications clientes. Chaque projet a à la fois un point de terminaison Project et un point de terminaison Azure OpenAI.
- Kit de développement logiciel (SDK) client : selon le point de terminaison que vous sélectionnez, vous pouvez choisir d’utiliser le Kit de développement logiciel (SDK) Microsoft Foundry ou le Kit de développement logiciel (SDK) OpenAI pour développer une application de conversation IA générative. Les deux kits SDK prennent en charge un objet client compatible avec l’API OpenAI qui peut envoyer des invites aux modèles, mais il existe des différences dans les fonctionnalités spécifiques disponibles dans chaque kit SDK.
- Authentification : selon le point de terminaison et le Kit de développement logiciel (SDK) que vous choisissez d’utiliser, il existe plusieurs façons d’authentifier une application cliente par Foundry afin d’accorder l’accès aux ressources. En général, les applications de production doivent utiliser l’authentification Microsoft Entra ID , ce qui oblige l’application à s’exécuter dans le contexte d’une identité spécifique ; mais dans certains scénarios, vous pouvez également utiliser l’authentification basée sur des clés ou des jetons .
- API de conversation : l’API cliente OpenAI prend en charge deux API de conversation : ChatCompletions et Réponses. Bien que l’API Réponses soit recommandée pour la plupart des nouveaux projets de développement, l’API ChatCompletions est bien établie et compatible sur de nombreux modèles et plateformes d’IA génératives.
Commençons par prendre en compte les points de terminaison disponibles, les kits SDK clients et les méthodes d’authentification. Nous allons explorer les API Réponses et ChatCompletions ultérieurement.
Utilisation du Kit de développement logiciel (SDK) Foundry avec le point de terminaison du projet
Le Kit de développement logiciel (SDK) Microsoft Foundry fournit un accès programmatique aux ressources de vos projets via une API REST et des bibliothèques clientes spécifiques au langage ; Y compris:
Note
Ce module utilise des exemples de code Python pour les tâches courantes. Vous pouvez faire référence à la documentation du Kit de développement logiciel (SDK) spécifique au langage pour obtenir du code équivalent dans votre langue préférée. Chaque KIT SDK est développé et géré indépendamment, de sorte que certaines fonctionnalités peuvent se trouver à différents stades de l’implémentation.
Installation du SDK
Pour utiliser la bibliothèque Azure ai Projects dans Python, installez le package azure-ai-projects à partir de PyPI, ainsi que les packages de prise en charge :
pip install azure-ai-projects azure-identity openai
Note
Lorsque vous utilisez le Kit de développement logiciel (SDK) Foundry pour développer une application de conversation, vous devez également importer le package sdk OpenAI . La fonctionnalité cliente de conversation dans le SDK Foundry est dérivée du Kit de développement logiciel (SDK) OpenAI.
Connexion au point de terminaison du projet
Chaque projet Foundry a un point de terminaison unique que vous pouvez trouver sur la page Overview du portail Foundry à https://ai.azure.com.
Le point de terminaison du projet suit ce format :
https://{resource-name}.services.ai.azure.com/api/projects/<project-name>
Utilisez ce point de terminaison pour créer un objet AIProjectClient :
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
)
Note
Le code utilise les informations d’identification par défaut Azure pour s’authentifier. Pour activer cette authentification, vous devez installer le package azure-identity (illustré dans la commande d’installation précédente).
Conseil / Astuce
Pour accéder au projet avec succès, le code doit s’exécuter dans une session Azure authentifiée. Par exemple, vous pouvez utiliser la commande Azure CLI az login pour vous connecter avant d’exécuter le code.
Le client de projet (AIProjectClient) fournit l’accès aux opérations natives Foundry qui n’ont pas d’équivalents OpenAI. Utilisez le client project pour :
- Récupérer les connexions de ressources
- Accéder à la configuration du projet
- Activer le traçage
- Gérer les jeux de données et les index
Création d’un client de conversation
Pour discuter avec un modèle dans votre projet Foundry, vous avez besoin d’un objet client compatible OpenAI. Vous pouvez utiliser la méthode get_openai_client() du client de projet pour en obtenir un, comme suit :
openai_client = project_client.get_openai_client(api_version="2024-10-21")
Vous pouvez ensuite utiliser cet objet client de conversation pour envoyer des invites aux modèles et retourner des réponses.
Utilisation du Kit de développement logiciel (SDK) OpenAI avec le point de terminaison Azure OpenAI
Le Kit de développement logiciel (SDK) OpenAI est la bibliothèque de client officielle pour appeler l’API OpenAI. Il gère les requêtes HTTP, l’authentification, les nouvelles tentatives et l’analyse de réponse. Le SDK fonctionne avec des modèles hébergés par OpenAI, des déploiements Azure OpenAI et des modèles Foundry à l’aide des mêmes modèles.
Installation du SDK
Pour utiliser la bibliothèque OpenAI dans Python, installez le package openai à partir de PyPI, ainsi que les packages de prise en charge :
pip install openai azure-identity
Note
Le package azure-identity est requis si vous envisagez d’utiliser l’authentification basée sur les jetons pour vous connecter au point de terminaison à l’aide des informations d’identification d’ID Microsoft Entra.
Connexion au point de terminaison Azure OpenAI
Chaque projet Foundry inclut un point de terminaison Azure OpenAI que vous pouvez trouver dans la page Vue d’ensemble du projet dans le portail Foundry à l’adresse https://ai.azure.com.
Le point de terminaison Azure OpenAI suit ce format :
https://{resource-name}.openai.azure.com/openai/v1
Créez un client OpenAI avec votre point de terminaison et vos informations d’identification Azure :
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,
)
Outre l’ID Microsoft Entra (recommandé), vous pouvez vous authentifier à l’aide d’une clé API ou de variables d’environnement.
Authentification par clé API :
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/"
)
Important
Utilisez les clés API avec précaution. Stockez-les en toute sécurité dans Azure Key Vault et ne les incluez jamais directement dans votre code.
Variables d’environnement :
Si vous définissez les variables d’environnement OPENAI_BASE_URL et OPENAI_API_KEY, le client les utilise automatiquement :
from openai import OpenAI
openai_client = OpenAI() # Uses environment variables
Quel que soit le mode d’authentification, le client OpenAI gère les opérations d’inférence de modèle. Utilisez-le pour :
- Génération de réponses avec l’API Réponses
- Complétions de chat et génération d’images
- Accès aux modèles directs Foundry (modèles non-Azure OpenAI)
Utilisation d’un objet client AzureOpenAI
Vous devez généralement utiliser l’objet client OpenAI pour discuter avec des modèles via le point de terminaison Azure OpenAI v1. Toutefois, vous avez également la possibilité de créer un objet client AzureOpenAI si vous devez utiliser des fonctionnalités à partir d’une version spécifique de l’API Azure OpenAI. Pour créer un objet client AzureOpenAI , vous devez spécifier la version de l’API et le point de terminaison Azure, comme suit :
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",
)
Choix entre le SDK Foundry et le Kit de développement logiciel (SDK) OpenAI
Microsoft Foundry prend en charge deux approches pour la création d’applications IA. Chacune d’elles a des objectifs différents et la compréhension de l’utilisation de chacune d’elles vous aide à créer la solution appropriée.
Quand utiliser le Kit de développement logiciel (SDK) Foundry
Utilisez le Kit de développement logiciel (SDK) Foundry lorsque votre application a besoin de fonctionnalités spécifiques à Foundry :
- Foundry Agent Service pour la création et la gestion d’agents IA
- Flux de travail d'invocation et d’approbation des outils
- Évaluations cloud pour le test et la validation des réponses IA
- Suivi et observabilité pour la surveillance du comportement de l’application
- Modèles Foundry directs (modèles non-Azure OpenAI disponibles dans le catalogue des modèles)
- Fonctionnalités de métadonnées, de connexions et de gouvernance du projet
Microsoft recommande le Kit de développement logiciel (SDK) Foundry lors de la création d’applications avec des agents, des évaluations ou des fonctionnalités spécifiques à Foundry.
Quand utiliser le Kit de développement logiciel (SDK) OpenAI
Utilisez le Kit de développement logiciel (SDK) OpenAI lorsque vous avez besoin d’une compatibilité maximale avec l’API OpenAI :
- Compatibilité complète de l’API OpenAI pour le code et les outils existants
- Portabilité entre les déploiements OpenAI et Azure OpenAI
- Complétions de conversation, réponses et images API
- Dépendance minimale sur les concepts spécifiques à Foundry
Le Kit de développement logiciel (SDK) OpenAI est idéal pour les charges de travail d’inférence de modèle dans lesquelles vous souhaitez que le code OpenAI existant fonctionne avec des modifications minimales. Toutefois, cette approche ne fournit pas de fonctionnalités spécifiques à Foundry telles que les agents ou les évaluations.
Microsoft Foundry vous offre une flexibilité quant à la façon dont vous créez des applications IA. Utilisez le Kit de développement logiciel (SDK) Foundry lorsque AIProjectClient vous avez besoin de fonctionnalités au niveau du projet telles que les agents, les évaluations, le suivi et les connexions. Utilisez le Kit de développement logiciel (SDK) OpenAI lorsque vous avez besoin d’une inférence de modèle simple avec une compatibilité OpenAI maximale. Les deux kits SDK fonctionnent avec votre point de terminaison de projet Foundry, ce qui vous permet de les combiner si nécessaire dans vos applications. Vous pouvez également utiliser les deux kits SDK dans la même application : le SDK Foundry pour les fonctionnalités de projet et le KIT DE développement logiciel (SDK) OpenAI pour l’inférence de modèle.