Ustawianie kontekstu projektu Foundry dla poleceń azd

Ważna

Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

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

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

Context Jak wygląda Użyj, gdy
W projekcie azd Uruchamiasz polecenie azd ai ... z katalogu zawierającego azure.yaml oraz aktywne środowisko azd. Tworzysz lub obsługujesz agenta w ramach projektu objętego śledzeniem i chcesz, aby środowisko określało, do którego projektu Foundry jest on kierowany.
Samodzielny Uruchamiasz azd ai ... w dowolnym innym katalogu. Wykonujesz doraźne zadania w istniejącym projekcie Foundry albo tworzysz skrypty do jednorazowych operacji w ramach automatyzacji, która nie ma własnego projektu azd.

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 azd ai agent (takie jak run, invokei optimize) nie są autonomiczne. Wymagają projektu azd do określania azure.yaml i środowiska. Użyj --agent-endpoint w azd ai agent invoke, aby wywołać wdrożonego agenta bez projektu azd na dysku.

Jak działa rozpoznawanie punktów końcowych

Dla każdego polecenia skierowanego do projektu Foundry CLI ustala punkt końcowy w tej kolejności. Pierwsze źródło zwracające wartość wygrywa, a późniejsze źródła nie są konsultowane:

  1. Flaga -p lub --project-endpoint w poleceniu. Zawsze wygrywa, niezależnie od kontekstu.
  2. azd Aktywne środowisko, jeśli znajdujesz się w katalogu projektu azd.
  3. Konfiguracja globalna, w sekcji extensions.ai-agents.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.

Punkt końcowy to jedyne, czego potrzebuje CLI. Ustala identyfikator zasobu usługi Azure Resource Manager (subskrypcję, grupę zasobów, konto i projekt) na podstawie punktu końcowego w momencie wywołania, dzięki czemu polecenia działają tak samo niezależnie od tego, czy punkt końcowy pochodzi ze środowiska, czy z konfiguracji globalnej.

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

Uwaga / Notatka

Tylko punkt końcowy jest kanoniczny. Polecenia zasobów ponownie określają subskrypcję, grupę zasobów, konto i projekt na podstawie punktu końcowego w momencie wywołania.

Wyczyść kontekst autonomiczny

azd ai project unset

To polecenie usuwa cały context blok z ~/.azd/config.json. Nie dotyka żadnych azd wartości środowiska.

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)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

Wewnątrz projektu azd wiersz Source ma zamiast tego treść azd env <env-name>, a wyświetlane wartości pochodzą z pliku .env środowiska, a nie z konfiguracji globalnej.

Lokalizacja usługi Storage

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

Tylko endpoint jest kanoniczny. Pozostałe pola istnieją po to, aby element azd ai project show był czytelny. Interfejs wiersza polecenia nigdy nie odczytuje ich podczas rozpoznawania obiektu docelowego. Plik można edytować ręcznie, ale azd ai project set i azd ai project unset to zalecany sposób zarządzania tym plikiem.

Pierwszeństwo wewnątrz projektu azd

W projekcie azd endpoint projektu aktywnego środowiska zawsze ma pierwszeństwo przed kontekstem globalnym. Uruchamianie azd ai project set z poziomu projektu nadal aktualizuje konfigurację globalną, ale interfejs wiersza polecenia wyświetla jednowierszowe ostrzeżenie, że środowisko nadal ma pierwszeństwo przed poleceniami uruchamianymi z tego katalogu.

To zachowanie jest zamierzone. Wartości środowiskowe na poziomie projektu są częścią procesu pracy zespołu, podczas gdy kontekst globalny jest ustawieniem specyficznym dla danej maszyny. Aby nadpisać ustawienie środowiska dla pojedynczego polecenia w projekcie, przekaż --project-endpoint, lub ustaw FOUNDRY_PROJECT_ENDPOINT w powłoce, zamiast korzystać z konfiguracji globalnej.

Treści powiązane

  • Last updated on