Définir le contexte du projet Foundry pour les commandes azd

Important

Les éléments marqués comme préversion dans cet article sont actuellement en préversion. Cette préversion est fournie sans contrat de niveau de service et Microsoft ne le recommande pas pour les charges de travail de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.

Les azd ai commandes s’exécutent dans deux contextes : à l’intérieur d’un azd projet (workflow d’équipe classique) et autonome (travail ad hoc, scripts ponctuels ou appels d’automatisation sans azure.yaml ancrage). Les deux modes ciblent les mêmes ressources Microsoft Foundry. Ils diffèrent uniquement par la manière dont l’interface en ligne de commande (CLI) détermine avec quel projet Foundry interagir. Dans cet article, vous allez découvrir l’ordre de résolution et comment définir le contexte autonome.

Prerequisites

  • Les extensions Azure Developer CLI Foundry ont été installées.
  • Session Azure authentifiée (azd auth login).
  • Point de terminaison de projet Foundry existant pour une utilisation autonome.

Quand utiliser chaque contexte

Context À quoi ça ressemble. À utiliser lorsque
Dans un azd projet Vous exécutez azd ai ... depuis un répertoire qui contient azure.yaml et un environnement azd actif. Vous générez ou exploitez un agent dans le cadre d’un projet suivi et souhaitez que l’environnement régisse le projet Foundry que vous ciblez.
Indépendant Vous exécutez azd ai ... depuis n’importe quel autre répertoire. Vous effectuez des tâches ad hoc sur un projet Foundry existant, ou vous automatisez par script des opérations ponctuelles depuis une automatisation qui n’est pas propriétaire d’un azd projet.

Les commandes de ressource (azd ai connection, , azd ai toolboxazd ai skillet azd ai routine) fonctionnent sur un projet Foundry unique. Ils ont donc besoin d’un point de terminaison de projet résolu à partir de l’un de ces contextes avant de pouvoir s’exécuter.

Les commandes de l’agent ont des exigences de contexte différentes. Le développement local nécessite un projet azd. Utilisez-le --agent-endpointazd ai agent invoke pour l’invocation sans projet. azd ai agent monitor <name> --session-id <id> fonctionne également en dehors d’un projet avec un contexte de projet global. Les commandes d’évaluation et d’optimisation prennent en charge les noms d’agents explicites et --project-endpoint; vérifiez l’aide de la commande individuelle.

Fonctionnement de la résolution des points de terminaison

Le projet principal, l’agent, la connexion, la boîte à outils, les skills et les résolveurs de routine utilisent les sources suivantes. Les commandes individuelles exposent différents sélecteurs ; les extensions facultatives de modèle et d’ajustement fin ont leurs propres commandes de configuration.

  1. L’indicateur --project-endpoint, sur les commandes qui l’exposent. La -p forme courte est propre à la commande ; par exemple, cela signifie --protocol sur agent invoke.
  2. FOUNDRY_PROJECT_ENDPOINT à partir de l’environnement azd actif. La valeur enregistrée prévaut. Si la clé est absente, l’hôte azd peut retourner la valeur du shell à ce stade.
  3. Configuration globale, sous extensions.ai-projects.context.endpoint dans ~/.azd/config.json. Voici ce que azd ai project set écrit.
  4. La variable d’environnement FOUNDRY_PROJECT_ENDPOINT dans le shell actuel.
  5. Erreur. L’interface CLI se termine par une suggestion structurée pour exécuter azd ai project set ou passer --project-endpoint.

Une valeur d’environnement persistante explicitement vide empêche le recours au shell à l’étape de l’environnement. Si aucun point de terminaison n’y est trouvé, l’interface CLI vérifie toujours la configuration globale, puis la variable shell. Les valeurs de point de terminaison non valides produisent une erreur de validation au lieu d’être acceptées.

azd ai project show utilise l’environnement sélectionné par azd env select; sa recherche de point de terminaison ne prend pas --environment en compte comme remplacement. Utilisez azd env select <name> avant d’inspecter un autre environnement.

Définir le contexte autonome

La commande azd ai project set enregistre l’endpoint du projet Foundry actif dans votre fichier de configuration global azd, de sorte que les commandes suivantes, exécutées depuis n’importe où, puissent omettre --project-endpoint. La commande prend le point de terminaison comme argument positionnel :

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project

La commande n’est pas interactive lorsque vous passez le point de terminaison. Ajoutez --no-prompt dans les scripts et la CI afin qu’une valeur manquante ou non résolue provoque immédiatement un échec, plutôt que de bloquer :

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt

Note

Seul le point de terminaison est canonique. Les commandes de ressources redéterminent l’abonnement, le groupe de ressources, le compte et le projet à partir du point de terminaison lors de l’appel.

Supprimer le contexte autonome

azd ai project unset

Cette commande efface le contexte du projet de la configuration globale, y compris le contexte de projet de l’agent hérité lorsqu’il est présent. Cela ne modifie aucune valeur d’environnement azd. L’exécution de celle-ci lorsqu’aucun contexte n’est défini réussit.

Examiner le contexte actif

La azd ai project show commande guide la chaîne de résolution complète et signale quelle source a fourni le point de terminaison actif. Utilisez-la pour confirmer les cibles de votre commande suivante avant de l’exécuter :

azd ai project show

Exemple de sortie lorsque le point de terminaison provient de la configuration globale :

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Set at:            <timestamp-recorded-by-project-set>

La sortie inclut le point de terminaison, la source et, pour la configuration globale, l’heure à laquelle elle a été définie. Il ne signale pas les détails du tenant ou de l’abonnement. À l’intérieur d’un projet azd, un endpoint issu de l’environnement s’affiche azd env (<env-name>). Utilisez --output json pour une sortie structurée.

Emplacement de stockage

Le contexte autonome se situe dans l’espace de noms extensions.ai-projects de ~/.azd/config.json:

{
  "extensions": {
    "ai-projects": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Le contexte stocke endpoint et setAt. L’extension de projet peut migrer l’entrée héritée extensions.ai-agents.project.context . Utilisez azd ai project unset et azd ai project set pour gérer le contexte.

Ordre de priorité dans un projet azd

À l’intérieur d’un projet azd, un point de terminaison non vide résolu à partir de l’environnement actif prévaut sur le contexte global. L’exécution de azd ai project set depuis un projet met à jour la configuration globale, et non l’environnement actif.

Les valeurs d’environnement au niveau du projet font partie du flux de travail de l’équipe, tandis que le contexte global est une préférence propre à chaque machine. Pour redéfinir l’environnement pour une seule commande de ressource, passez --project-endpoint si cette option est prise en charge. La définition d’une variable shell ne remplace pas une valeur d’environnement persistante.

Configurer un projet pour le provisionnement

project set sélectionne un point de terminaison global ; il ne déclare pas l’infrastructure. Utilisez project add pour ajouter ou mettre à jour le service azure.ai.project dans azure.yaml:

azd ai project add --project-id "<project-resource-id>"

Vous pouvez également utiliser --project-endpoint <endpoint> pour une référence de point de terminaison uniquement ou --new-project pour configurer un nouveau projet. --project-id enregistre les deux, le point de terminaison et AZURE_AI_PROJECT_ID; une référence de point de terminaison uniquement n’enregistre pas d’ID de ressource ARM. Utilisez --force pour remplacer un autre projet configuré.

Ajouter un déploiement de modèle managé

Avant d’éjecter l’infrastructure, ajoutez un déploiement de modèle à la déclaration inline du projet :

azd ai project deployment add --model OpenAI/gpt-4.1 --name chat
azd provision

Utilisez --version, --sku, --capacityet --location pour sélectionner les paramètres de déploiement. --force permet le remplacement d’une déclaration inline conflictuelle. La add commande modifie la déclaration ; azd provision l’applique.

Pour devenir propriétaire des fichiers d’infrastructure, utilisez azd ai project add --infra=bicep ou --infra=terraform. Sans infrastructure d’application existante, l’éjection utilise infra par défaut. Lors de la conservation de l’infrastructure d’application existante, elle ajoute une couche Foundry sous infra/foundry; les configurations en couches existantes conservent leurs chemins déclarés.

Inspectez la configuration du projet local

Utilisez azd ai project context pour inspecter le contexte du projet et de l’environnement azd. Contrairement à project show, qui signale la résolution du point de terminaison, la sortie de contexte peut inclure des valeurs d’environnement et des secrets. Ne le partagez pas et ne le validez pas dans le contrôle de code source.

Contenu connexe

  • Dernière mise à jour :