Ustawianie kontekstu projektu Foundry dla poleceń azd

Polecenia azd ai działają w dwóch kontekstach: w projekcie azd (typowy przepływ pracy zespołu) oraz samodzielnie (praca ad hoc, jednorazowe skrypty lub wywołania z automatyzacji, które nie mają projektu azure.yaml, względem którego mogłyby się zakotwiczyć). Oba tryby są przeznaczone dla tych samych zasobów Microsoft Foundry. Różnią się one tylko tym, w jaki sposób interfejs wiersza polecenia określa, z którym projektem Foundry porozmawiać. W tym artykule dowiesz się, jaka jest kolejność rozstrzygania i jak ustawić kontekst autonomiczny.

Wymagania wstępne

• Zainstalowano rozszerzenia Azure Developer CLI Foundry.
• Uwierzytelniona sesja Azure (azd auth login).
• Istniejący punkt końcowy projektu Foundry do użytku autonomicznego.

Kiedy należy używać każdego kontekstu

Polecenia zasobów (azd ai connection, azd ai toolbox, azd ai skilli azd ai routine) działają w ramach pojedynczego projektu Foundry, więc muszą one rozpoznać punkt końcowy projektu z jednego z tych kontekstów przed uruchomieniem.

Polecenia agenta mają różne wymagania dotyczące kontekstu. Lokalne programowanie wymaga projektu azd. Użyj polecenia --agent-endpoint w azd ai agent invoke do wywołania bez projektu. azd ai agent monitor <name> --session-id <id> działa również poza projektem z kontekstem projektu globalnego. Polecenia oceny i optymalizacji obsługują określone jawnie nazwy agentów i --project-endpoint; sprawdź pomoc poszczególnych poleceń.

Jak działa rozpoznawanie punktów końcowych

Podstawowy projekt, agent, połączenie, przybornik, umiejętność i moduły rozstrzygania rutyn używają następujących źródeł. Poszczególne polecenia uwidaczniają różne selektory; Opcjonalne rozszerzenia modelu i dostrajania mają własne polecenia konfiguracji.

1. Flaga --project-endpoint w poleceniach, które ją udostępniają. Krótka forma -p zależy od polecenia; na przykład na agent invoke oznacza --protocol.
2. FOUNDRY_PROJECT_ENDPOINT z aktywnego azd środowiska. Zapisana wartość ma pierwszeństwo. Jeśli klucz jest nieobecny, host azd może zwrócić wartość shella na tym etapie.
3. Konfiguracja globalna, w sekcji extensions.ai-projects.context.endpoint w ~/.azd/config.json. To właśnie azd ai project set pisze.
4. Zmienna środowiskowa FOUNDRY_PROJECT_ENDPOINT w bieżącej powłoce.
5. Błąd. CLI kończy pracę, wyświetlając uporządkowaną sugestię uruchomienia azd ai project set lub przekazania --project-endpoint.

Jawnie pusta wartość utrwalonej wartości środowiskowej uniemożliwia mechanizm awaryjny powłoki na etapie środowiska. Jeśli żaden punkt końcowy nie wskazuje tam, interfejs wiersza polecenia nadal sprawdza konfigurację globalną, a następnie zmienną powłoki. Nieprawidłowe wartości punktu końcowego generują błąd weryfikacji zamiast przejść dalej.

azd ai project show używa środowiska wybranego przez azd env select; jego wyszukiwanie punktu końcowego nie uwzględnia --environment jako nadpisania. Przed sprawdzeniem innego środowiska należy użyć polecenia azd env select <name> .

Ustawianie autonomicznego kontekstu

Polecenie azd ai project set zapisuje endpoint aktywnego projektu Foundry do globalnej konfiguracji azd, dzięki czemu kolejne polecenia uruchamiane z dowolnego miejsca mogą pomijać --project-endpoint. Polecenie przyjmuje punkt końcowy jako argument pozycyjny:

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

Polecenie jest w pełni nieinterakcyjne podczas przekazywania punktu końcowego. Dodaj --no-prompt do skryptów i CI, tak aby brakująca lub nieustalona wartość natychmiast powodowała błąd zamiast blokować:

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

Wyczyść kontekst autonomiczny

azd ai project unset

To polecenie czyści kontekst projektu z konfiguracji globalnej, w tym również starszy kontekst agenta-projektu, jeśli występuje. Nie dotyka żadnych azd wartości środowiska. Uruchomienie go, gdy nie ustawiono żadnego kontekstu, kończy się powodzeniem.

Sprawdzanie aktywnego kontekstu

Polecenie azd ai project show przechodzi przez cały łańcuch rozstrzygania i wskazuje, które źródło dostarczyło aktywny punkt końcowy. Użyj tego, aby potwierdzić, czego dotyczy Twoje następne polecenie, przed jego uruchomieniem:

azd ai project show

Przykładowe dane wyjściowe, gdy punkt końcowy pochodzi z konfiguracji globalnej:

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>

Dane wyjściowe obejmują punkt końcowy, źródło i, dla konfiguracji globalnej, czas jego ustawienia. Nie zgłasza szczegółów dzierżawcy ani subskrypcji. azd Wewnątrz projektu wyświetlany jest punkt końcowy pochodzący ze środowiska azd env (<env-name>). Użyj --output json do ustrukturyzowanych danych wyjściowych.

Lokalizacja usługi Storage

Samodzielny kontekst znajduje się w przestrzeni nazw extensions.ai-projects w ~/.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"
      }
    }
  }
}

Kontekst przechowuje endpoint i setAt. Rozszerzenie projektu może migrować starszy wpis extensions.ai-agents.project.context. Użyj azd ai project set i azd ai project unset, aby zarządzać kontekstem.

Pierwszeństwo wewnątrz projektu azd

Wewnątrz projektu azd niepusty punkt końcowy ustalony z aktywnego środowiska ma pierwszeństwo przed kontekstem globalnym. Uruchamianie azd ai project set z poziomu projektu aktualizuje konfigurację globalną, a nie aktywnego środowiska.

Wartości środowiska na poziomie projektu są częścią przepływu pracy zespołu, a kontekst globalny jest preferencją dla poszczególnych maszyn. Aby nadpisać ustawienie środowiska dla pojedynczego polecenia dotyczącego zasobu, przekaż --project-endpoint, jeśli jest to obsługiwane. Ustawienie zmiennej powłoki nie zastępuje utrwalonej wartości środowiska.

Konfigurowanie projektu do aprowizacji

project set wybiera globalny punkt końcowy; nie deklaruje infrastruktury. Użyj polecenia project add, aby dodać lub zaktualizować usługę azure.ai.project w azure.yaml:

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

Alternatywnie należy użyć odwołania --project-endpoint <endpoint> tylko do punktu końcowego lub użyć --new-project, aby skonfigurować nowy projekt. --project-id rejestruje zarówno punkt końcowy, jak i AZURE_AI_PROJECT_ID; odwołanie tylko do punktu końcowego nie rejestruje identyfikatora zasobu ARM. Użyj polecenia --force, aby przełączyć się na inny skonfigurowany projekt.

Dodawanie wdrożenia modelu zarządzanego

Przed wyodrębnieniem infrastruktury dodaj wdrożenie modelu do wbudowanej deklaracji projektu:

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

Użyj --version, --sku, --capacity i --location, aby wybrać ustawienia wdrożenia. --force umożliwia zastąpienie deklaracji wbudowanej powodującej konflikt. Polecenie add zmienia deklarację; azd provision stosuje ją.

Aby przejąć własność plików infrastruktury, użyj polecenia azd ai project add --infra=bicep lub --infra=terraform. Bez istniejącej infrastruktury aplikacji domyślna wartość ejection to infra. Podczas zachowywania istniejącej infrastruktury aplikacji dodaje warstwę Foundry pod infra/foundry; istniejące konfiguracje warstwowe zachowują zadeklarowane ścieżki.

Sprawdzanie konfiguracji projektu lokalnego

Użyj azd ai project context polecenia , aby sprawdzić kontekst projektu azd i środowiska. W przeciwieństwie do project show, które raportuje ustalanie punktu końcowego, dane wyjściowe kontekstu mogą zawierać wartości środowiska i sekrety. Nie udostępniaj go ani nie commituj .azure do kontroli wersji.

Treści powiązane

• Szybki start: wdrażanie pierwszego hostowanego agenta
• Instalowanie rozszerzeń interfejsu wiersza polecenia dewelopera Azure Developer Foundry
• Inicjowanie projektu hostowanego agenta przy użyciu interfejsu wiersza polecenia dewelopera Azure
• Optymalizowanie istniejącego agenta bez plików projektu AZD