Настройка контекста проекта Foundry для команд azd

Important

Элементы, помеченные предварительным просмотром в этой статье, в настоящее время находятся в предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и Microsoft не рекомендует использовать её для рабочих нагрузок в производственной среде. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.

Команды azd ai выполняются в двух контекстах: внутри проекта azd (типичный командный рабочий процесс) и автономно (разовые задачи, одноразовые сценарии или вызовы из средств автоматизации, у которых нет azure.yaml, к которому можно было бы привязаться). Оба режима нацелены на одни и те же ресурсы Microsoft Foundry. Они отличаются только тем, как CLI определяет, с каким проектом Foundry взаимодействовать. В этой статье вы узнаете порядок разрешения и то, как задать автономный контекст.

Необходимые условия

  • Установлено расширение Foundry для Azure Developer CLI.
  • Аутентифицированный сеанс Azure (azd auth login).
  • Существующая конечная точка проекта Foundry для самостоятельного использования.

Когда следует использовать каждый контекст

Контекст Как выглядит Используйте, если
В azd проекте Вы запускаете azd ai ... из каталога, содержащего azure.yaml, при активированной среде azd. Вы создаете или управляете агентом в рамках отслеживаемого проекта и хотите, чтобы среда управляла целевым проектом Foundry.
Автономный Вы запускаете azd ai ... из любого другого каталога. Вы выполняете разовые задачи в существующем проекте Foundry или запускаете разовые операции с помощью средств автоматизации, не связанных с проектом azd.

Команды ресурсов (azd ai connection, azd ai toolbox, azd ai skill и azd ai routine) работают с одним проектом Foundry, поэтому перед выполнением для них требуется конечная точка проекта, определённая на основе одного из этих контекстов.

Для некоторых azd ai agent команд требуется azd проект, так как они работают с определениями локальных служб. Другие команды поддерживают автономное использование. Например, azd ai agent optimize может указывать на уже развернутый агент, если задать его имя и определить конечную точку проекта Foundry из глобальной конфигурации, с помощью явного флага или из переменной среды. --agent-endpoint Используйте azd ai agent invoke для вызова развернутого агента без azd проекта на диске.

Как работает разрешение конечных точек

Для каждой команды, которая относится к проекту Foundry, CLI определяет конечную точку в следующем порядке. Первый источник, который возвращает значение, имеет приоритет, а к последующим источникам не обращаются:

  1. Флаг -p или --project-endpoint в команде. Всегда выигрывает, независимо от контекста.
  2. Активная azd среда, если вы находитесь в каталоге проекта azd.
  3. Глобальная конфигурация, в разделе extensions.ai-agents.context.endpoint в ~/.azd/config.json. Вот что пишет azd ai project set.
  4. переменная среды FOUNDRY_PROJECT_ENDPOINT в текущей оболочке.
  5. Ошибка. CLI завершает работу, выдавая структурированную рекомендацию запустить azd ai project set или передать --project-endpoint.

Конечная точка является единственной вещью, необходимой интерфейсом командной строки. Он определяет идентификатор ресурса Azure Resource Manager (подписку, группу ресурсов, учетную запись и проект) по конечной точке в момент вызова, поэтому команды работают одинаково независимо от того, получают ли они конечную точку из вашей среды или из глобальной конфигурации.

Настройка автономного контекста

Команда azd ai project set записывает эндпоинт активного проекта Foundry в ваш глобальный файл конфигурации azd, поэтому в последующих командах, запускаемых из любого места, можно не указывать --project-endpoint. Команда принимает конечную точку в качестве позиционного аргумента:

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

Команда работает полностью в неинтерактивном режиме, если указать конечную точку. Добавьте --no-prompt в скрипты и CI, чтобы отсутствующее или неразрешённое значение сразу вызывало ошибку, а не приводило к блокировке:

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

Замечание

Только конечная точка является канонической. Команды ресурсов при вызове повторно определяют подписку, группу ресурсов, учетную запись и проект на основе конечной точки.

Очистка автономного контекста

azd ai project unset

Эта команда удаляет весь context блок из ~/.azd/config.json. Не затрагивает никакие azd значения переменных среды.

Проверка активного контекста

Команда azd ai project show проходит полную цепочку разрешения и сообщает, какой источник предоставил активную конечную точку. Используйте это, чтобы перед выполнением подтвердить, на что нацелена ваша следующая команда:

azd ai project show

Пример вывода, когда эндпоинт берётся из глобальной конфигурации:

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

В проекте azd строка Source вместо этого гласит azd env <env-name>, а отображаемые значения берутся из файла .env среды, а не из глобальной конфигурации.

Расположение хранилища

Автономный контекст находится в пространстве имен extensions.ai-agents в ~/.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"
      }
    }
  }
}

Только endpoint канонично. Остальные поля нужны, чтобы azd ai project show было удобно читать. Интерфейс командной строки никогда не считывает их при разрешении целевого объекта. Вы можете редактировать файл вручную, но azd ai project set и azd ai project unset — это поддерживаемый способ управления им.

Приоритет в проекте azd

В проекте azd конечная точка проекта активной среды всегда имеет приоритет над глобальным контекстом. Запуск azd ai project set из проекта по-прежнему обновляет глобальную конфигурацию, но интерфейс командной строки выводит однострочный предупреждение о том, что среда продолжает иметь приоритет для команд, выполняемых из этого каталога.

Это поведение является преднамеренным. значения среды на уровне Project являются частью рабочего процесса команды, а глобальный контекст — это предпочтения для каждого компьютера. Чтобы переопределить окружение для одной команды, находясь в проекте, передайте --project-endpoint или задайте FOUNDRY_PROJECT_ENDPOINT в оболочке вместо того, чтобы полагаться на глобальную конфигурацию.

Связанный контент

  • Последнее обновление: