Ange foundry-projektkontexten för azd-kommandon

Viktigt

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Kommandona azd ai körs i två kontexter: i ett azd projekt (det typiska teamarbetsflödet) och fristående (ad hoc-arbete, engångsskript eller anrop från automatisering som inte har något azure.yaml att förankra på). Båda lägena är inriktade på samma Microsoft Foundry-resurser. De skiljer sig bara åt i hur CLI avgör vilket Foundry-projekt som ska kommunicera med. I den här artikeln får du lära dig lösningsordningen och hur du ställer in den fristående kontexten.

Förutsättningar

När du ska använda varje kontext

Context Hur det ser ut Använd när
I ett azd projekt Du kör azd ai ... från en katalog som innehåller azure.yaml och en aktiv azd miljö. Du skapar eller driver en agent som en del av ett spårat projekt och vill att miljön ska styra vilket Foundry-projekt du riktar in dig på.
Fristående Du kör azd ai ... från vilken annan katalog som helst. Du utför ad hoc-arbete mot ett befintligt Foundry-projekt, eller så skriptar du engångsåtgärder från automatisering som inte äger ett azd projekt.

Resurskommandona (azd ai connection, azd ai toolbox, azd ai skilloch azd ai routine) fungerar på ett enda Foundry-projekt, så de behöver en projektslutpunkt som löses från någon av dessa kontexter innan de kan köras.

Kommandona azd ai agent (till exempel run, invokeoch optimize) är inte fristående. De kräver ett azd projekt för azure.yaml och miljöidentifiering. Använd --agent-endpoint på azd ai agent invoke för att anropa en distribuerad agent utan ett azd projekt på disk.

Så här fungerar slutpunktsupplösning

För varje kommando som riktar sig mot ett Foundry-projekt löser CLI slutpunkten i den här ordningen. Den första källan som returnerar ett värde vinner och senare källor konsulteras inte:

  1. Flaggan -p eller --project-endpoint för kommandot. Vinner alltid, oavsett kontext.
  2. Den aktiva azd-miljön, om du är i en azd-projektkatalog.
  3. Global konfiguration, under extensions.ai-agents.context.endpoint i ~/.azd/config.json. Det här är vad azd ai project set skriver.
  4. Miljövariabeln FOUNDRY_PROJECT_ENDPOINT i det aktuella skalet.
  5. Fel. CLI avslutas med ett strukturerat förslag om att köra azd ai project set eller skicka --project-endpoint.

Slutpunkten är det enda CLI behöver. Den fastställer Azure Resource Managers resurs-ID (prenumeration, resursgrupp, konto och projekt) utifrån slutpunkten vid anropstillfället, så att kommandon fungerar på samma sätt oavsett om de fick slutpunkten från din miljö eller din globala konfiguration.

Ange den fristående kontexten

Kommandot azd ai project set skriver ändpunkten för det aktiva Foundry-projektet till din globala azd-konfiguration, så att efterföljande kommandon som körs var som helst kan utelämna --project-endpoint. Kommandot tar slutpunkten som ett positionsargument:

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

Kommandot körs helt utan användarinteraktion när du anger ändpunkten. Lägg till --no-prompt i skript och CI så att det snabbt uppstår ett fel om ett värde saknas eller inte kan lösas, i stället för att blockera:

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

Note

Endast slutpunkten är kanonisk. Resurskommandon härleder på nytt prenumerationen, resursgruppen, kontot och projektet från slutpunkten när anropet görs.

Rensa den fristående kontexten

azd ai project unset

Det här kommandot tar bort hela context blocket från ~/.azd/config.json. Det berör inte några azd miljövärden.

Granska den aktiva kontexten

Kommandot azd ai project show vägleder hela lösningskedjan och rapporterar vilken källa som tillhandahöll den aktiva slutpunkten. Använd den för att bekräfta vad nästa kommando har som mål innan du kör det:

azd ai project show

Exempelutdata när slutpunkten kommer från global konfiguration:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

I ett azd-projekt lyder raden Source i stället azd env <env-name>, och de visade värdena kommer från miljöns .env-fil snarare än från global konfiguration.

Lagringsplats

Den fristående kontexten extensions.ai-agents finns under namnområdet i ~/.azd/config.json:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Endast endpoint är kanonisk. De andra fälten finns för att göra azd ai project show läsbara. CLI:t läser dem aldrig när det fastställer ett mål. Du kan redigera filen för hand, men azd ai project set och azd ai project unset är det sätt som stöds för att hantera den.

Prioritetsordning i ett azd-projekt

I ett azd projekt vinner den aktiva miljöns projektslutpunkt alltid över den globala kontexten. Om du kör azd ai project set inifrån ett projekt uppdateras fortfarande den globala konfigurationen, men CLI skriver ut en enradsvarning om att miljön fortsätter att ha företräde för kommandon som körs från den katalogen.

Det här beteendet är avsiktligt. Miljövärden på projektnivå är en del av teamets arbetsflöde, medan den globala konfigurationen är en inställning för varje dator. Om du vill åsidosätta miljön för ett enskilt kommando inifrån ett projekt, skicka --project-endpoint, eller ange FOUNDRY_PROJECT_ENDPOINT i skalet, i stället för att förlita dig på global konfiguration.

Relaterat innehåll

  • Last updated on