Nastavení kontextu projektu Foundry pro příkazy azd

Important

Položky označené jako náhled v tomto článku jsou aktuálně ve verzi Preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a Microsoft ji nedoporučuje pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Příkazy azd ai se spouštějí ve dvou kontextech: uvnitř azd projektu (typický týmový pracovní postup) a samostatné (ad hoc práce, jednorázové skripty nebo vyvolání z automatizace, která nemá azure.yaml ukotvení). Oba režimy cílí na stejné prostředky Microsoft Foundry. Liší se pouze v tom, jak rozhraní příkazového řádku určuje, se kterým projektem Foundry se má mluvit. V tomto článku se seznámíte s pořadím řešení a nastavením samostatného kontextu.

Předpoklady

  • Rozšíření Azure Developer CLI Foundry byla nainstalována.
  • Autentizovaná relace Azure (azd auth login).
  • Existující koncový bod projektu Foundry pro samostatné použití.

Kdy použít každý kontext

Context Jak to vypadá Použít, když
V azd projektu Spouštíte azd ai ... z adresáře, který obsahuje azure.yaml a aktivní azd prostředí. Sestavíte nebo provozujete agenta jako součást sledovaného projektu a chcete, aby prostředí řídilo, na který projekt Foundry cílíte.
Samostatné Spustíte azd ai ... z jakéhokoli jiného adresáře. Provádíte ad hoc práci v rámci existujícího projektu Foundry nebo vytváříte skripty pro jednorázové operace z automatizace, která nevlastní projekt azd.

Příkazy zdrojů (azd ai connection, azd ai toolbox, azd ai skilla azd ai routine) pracují s jedním projektem Foundry, takže před spuštěním potřebují koncový bod projektu vyřešený z jednoho z těchto kontextů.

Některé azd ai agent příkazy vyžadují azd projekt, protože pracují s definicemi místní služby. Jiné příkazy podporují samostatné použití. Například azd ai agent optimize se může zaměřit na existujícího nasazeného agenta, když zadáte jeho název a určíte koncový bod projektu Foundry z globální konfigurace, explicitně zadaného přepínače nebo proměnné prostředí. Použijte --agent-endpoint na azd ai agent invoke k volání nasazeného agenta bez projektu azd na disku.

Jak funguje určování koncových bodů

U každého příkazu určeného pro projekt Foundry CLI určí endpoint v tomto pořadí. První zdroj, který vrací hodnotu vyhrává, a pozdější zdroje se nekonzultují:

  1. Příznak -p nebo --project-endpoint u příkazu. Vždy vyhrává bez ohledu na kontext.
  2. Aktivní prostředí azd, pokud se nacházíte v adresáři projektu azd.
  3. Globální konfigurace, pod extensions.ai-agents.context.endpoint v ~/.azd/config.json. To je to, co azd ai project set píše.
  4. Proměnná prostředí FOUNDRY_PROJECT_ENDPOINT v aktuálním shellu.
  5. Chyba. CLI se ukončí a zobrazí strukturované doporučení spustit azd ai project set nebo zadat --project-endpoint.

Koncový bod je jediná věc, kterou rozhraní příkazového řádku potřebuje. Při volání určuje z koncového bodu ID prostředku ve službě Azure Resource Manager (předplatné, skupinu prostředků, účet a projekt), takže příkazy fungují stejně bez ohledu na to, zda získaly koncový bod z vašeho prostředí nebo z vaší globální konfigurace.

Nastavení samostatného kontextu

Příkaz azd ai project set zapíše koncový bod aktivního projektu Foundry do globální konfigurace azd, takže následné příkazy spouštěné odkudkoli mohou vynechat --project-endpoint. Příkaz převezme koncový bod jako poziční argument:

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

Příkaz je při předání koncového bodu plně neinteraktivní. Přidejte --no-prompt do skriptů a CI, aby chybějící nebo nevyřešená hodnota rychle selhala, místo aby blokovala:

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

Poznámka:

Pouze koncový bod je kanonický. Příkazy prostředků znovu odvozují předplatné, skupinu prostředků, účet a projekt z koncového bodu v době volání.

Vymazání samostatného kontextu

azd ai project unset

Tento příkaz odebere celý context blok z ~/.azd/config.jsonobjektu . Nedotkne se žádné azd hodnoty prostředí.

Kontrola aktivního kontextu

Příkaz azd ai project show projde celý řetězec vyhodnocení a oznámí, který zdroj poskytl aktivní koncový bod. Použijte ho k ověření, na co cílí váš další příkaz, než ho spustíte:

azd ai project show

Ukázkový výstup, když koncový bod pochází z globální konfigurace:

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

Uvnitř projektu azd má řádek Source místo toho hodnotu azd env <env-name> a zobrazené hodnoty pocházejí ze souboru .env daného prostředí, nikoli z globální konfigurace.

Umístění úložiště

Samostatný kontext je umístěn v jmenném prostoru extensions.ai-agents v ~/.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"
      }
    }
  }
}

Jen endpoint je kanonický. Ostatní pole existují, aby byla azd ai project show čitelná. CLI je při určování cíle nikdy nečte. Soubor můžete upravovat ručně, ale azd ai project setazd ai project unset je to podporovaný způsob, jak ho spravovat.

Priorita v projektu azd

V projektu azd má koncový bod projektu aktivního prostředí vždy přednost před globálním kontextem. Spuštění azd ai project set z projektu stále aktualizuje globální konfiguraci, ale rozhraní příkazového řádku vytiskne jednořádkové upozornění, že prostředí bude mít nadále přednost před příkazy spuštěnými z daného adresáře.

Toto chování je záměrné. Hodnoty prostředí na úrovni projektu jsou součástí pracovního postupu týmu, zatímco globální kontext je nastavením pro jednotlivé počítače. Chcete-li v rámci projektu přepsat nastavení prostředí pro jeden příkaz, předejte --project-endpoint nebo v shellu nastavte FOUNDRY_PROJECT_ENDPOINT místo spoléhání se na globální konfiguraci.

Související obsah

  • Poslední aktualizace v