Начните работу с LangChain и LangGraph с Foundry

Используйте пакет langchain-azure-ai в качестве точки входа для создания приложений LangChain и LangGraph с возможностями Microsoft Foundry. Эта статья предоставляет обзор пакета, чтобы вы могли быстро начать работу, а затем перейти к соответствующей углубленной документации для каждой функциональности.

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

  • Подписка Azure. Создайте его бесплатно.
  • Проект Foundry.
  • Роль пользователя Azure AI в проекте Foundry (роль с минимальными привилегиями для разработки). Если вы также создаете ресурсы или управляете ими, используйте участника или владельца по мере необходимости. Дополнительные сведения см. в разделе Управление доступом на основе ролей в Microsoft Foundry.
  • Python 3.10 или более поздней версии.
  • Azure CLI вошел в систему (az login), чтобы DefaultAzureCredential могла пройти проверку подлинности.

Совет

В этой статье упоминается поддержка Microsoft Foundry (new), которая использует версию azure-ai-projects>=2.0. Если вы используете классическую версию Foundry, используйте langchain-azure-ai[v1] вместо этого.

Установка пакета

Установите базовый пакет:

pip install -U langchain-azure-ai azure-identity

Установите дополнительные компоненты в зависимости от вашего сценария.

pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"
  • Используйте [tools] , если приложение использует средства из пространства langchain_azure_ai.tools.*имен, например Аналитика документов.
  • Используйте [opentelemetry], если вам требуется интеграция трассировки с помощью OpenTelemetry.

Выбор блоков интеграции

Используйте эту карту, чтобы выбрать подходящее пространство имен для решения:

Возможность Пространства имен Типичное использование
Служба агента Foundry langchain_azure_ai.agents Построение управляемых агентом узлов для разработки сложных графов и потоков для LangGraph и LangChain. См. подробные примеры.
Безопасность содержимого Foundry langchain_azure_ai.agents.middleware Используйте систему "Безопасность контента и управление", чтобы гарантировать возможность развертывания решения с соответствующими ограничителями. См. подробные примеры.
Модели чата langchain_azure_ai.chat_models Вызов моделей чата Azure OpenAI и каталогов моделей. См. подробные примеры.
Эмбеддинги langchain_azure_ai.embeddings Вызов моделей эмбеддинга из каталога и создание векторов для поиска, извлечения и ранжирования процессов. См. подробные примеры.
Векторные хранилища langchain_azure_ai.vectorstores Используйте векторные интеграции Поиск с использованием ИИ Azure и Cosmos DB.
Ретриверы langchain_azure_ai.retrievers Выполните извлечение по Azure поддерживаемым индексам и хранилищам.
Хранилища истории чатов langchain_azure_ai.chat_message_histories Поддержание и воспроизведение истории чата между сеансами. Используйте журналы, управляемые памятью, чтобы получить консолидированный журнал чата. См. подробные примеры.
Инструменты langchain_azure_ai.tools Добавьте такие средства, как Аналитика документов, Компьютерное зрение, аналитика текста в сфере здравоохранения и Logic Apps.
Обратные вызовы и трассировка langchain_azure_ai.callbacks Запись событий выполнения и выдача трассировок OpenTelemetry. См. подробные примеры.
Конструкторы запросов langchain_azure_ai.query_constructors Создайте фильтры запросов, ориентированные на серверную часть для сценариев восстановления данных.

См. раздел Учимся каждой возможности в деталях для получения конкретных пошаговых руководств.

Подключение к конечным точкам проекта и учетным данным

Многие langchain-azure-ai классы поддерживают подключение через конечную точку проекта Foundry. Установите AZURE_AI_PROJECT_ENDPOINT один раз, а затем повторно используйте его в поддерживаемых классах.

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

При использовании project_endpoint аутентификация использует Microsoft Entra ID и Azure RBAC в проекте.

Ключи API предназначены для прямых конечных точек службы, таких как /openai/v1.

export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"

Пример. Использование моделей Foundry

После настройки переменных среды можно использовать модель следующим образом:

import langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-5.2")

Вы также можете настроить клиенты специально. Например, давайте рассмотрим AzureAIOpenAIApiChatModel как представительский шаблон.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

# Option A: Use a Foundry project endpoint (Microsoft Entra ID required).
model_from_project = AzureAIOpenAIApiChatModel(
  project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option B: Use a service endpoint directly.
model_from_endpoint = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential="super-secret",
  model="gpt-5.2",
)

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

К инструментам можно применить тот же шаблон. Например, можно использовать AzureAIDocumentIntelligenceTool и конечную точку проекта DefaultAzureCredential без дополнительной настройки, когда AZURE_AI_PROJECT_ENDPOINT установлено.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Как DefaultAzureCredential работает

DefaultAzureCredential последовательно тестирует несколько источников учетных данных Microsoft Entra ID и использует первый, который работает. Распространенными источниками являются переменные среды, управляемая идентичность, средства разработчика и Azure CLI.

Используйте DefaultAzureCredential в качестве значения по умолчанию для локальной разработки и развернутых рабочих нагрузок. Если вам нужен более строгий элемент управления, замените его определенными учетными данными, такими как AzureCliCredential для локальной разработки или ManagedIdentityCredential для рабочих нагрузок в Azure.

Тот же шаблон конечной точки проекта также используется другими классами.

Подробные сведения о каждой возможности

Начните с этих руководств в этом наборе документации:

Используйте эти ресурсы пакета для сведений и обновлений на уровне модуля:

Следующий шаг

Используйте модели Foundry с LangChain

  • Last updated on