Разработка приложений с помощью моделей и LangChain в Microsoft Foundry (классическая модель)

LangChain — это экосистема для разработчиков, которая упрощает создание приложений для логического вывода. Он включает несколько компонентов, и большинство из них можно использовать независимо, поэтому вы можете выбрать подходящие элементы.

Модели, развернутые в Microsoft Foundry с помощью LangChain можно использовать двумя способами:

В этом руководстве показано, как использовать пакет langchain-azure-ai[v1] с LangChain с помощью API вывода Azure модели ИИ. Некоторые модели, такие как OpenAI, Cohere или Mistral, предлагают собственные API и расширения LangChain. Эти расширения могут включать возможности для конкретных моделей и подходят, если вам нужно использовать их. Установите расширение для выбранной модели, например langchain-openai или langchain-cohere.

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

Чтобы запустить это руководство, вам потребуется:

• Учетная запись Azure с активной подпиской. Если у вас нет, создайте учетную запись free Azure, которая включает бесплатную пробную подписку.

• Требуемая роль:
  • Владелец или участник ресурса Foundry или Центра искусственного интеллекта для развертывания моделей
  • Пользователь Azure ИИ для использования модели в проекте Foundry
  • Azure Разработчик ИИ для использования модели в рамках проекта на основе хаба

• Развертывание модели, поддерживающее API вывода моделей. В этой статье используется Mistral-Large-3.

• Установленная Python 3.9 или более поздняя версия, включая и pip.

• LangChain установлен. Ее можно установить с помощью следующей команды:

  pip install langchain
  

• Установите интеграцию Foundry:

  pip install -U langchain-azure-ai[v1]
  

Настройка среды

Чтобы использовать LLM, развернутые на портале Foundry Microsoft, вам потребуется конечная точка и учетные данные для подключения к нему. Выполните следующие действия, чтобы получить необходимые сведения из модели, которую вы хотите использовать:

1. Войдите в Microsoft Foundry. Убедитесь, что переключатель New Foundry включен. Эти действия относятся к Foundry (new).

   

2. Откройте проект, в котором развернута модель, если она еще не открыта.

3. Скопируйте URL-адрес конечной точки и ключ.

В этом сценарии задайте URL-адрес конечной точки и ключ в качестве переменных среды. (Если скопированная конечная точка содержит дополнительный текст после /models, удалите его, чтобы URL-адрес закончился /models , как показано ниже.)

export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

Создайте клиент для подключения к модели чата AzureAIChatCompletionsModel с помощью класса.

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

Что делает этот фрагмент кода: Создает экземпляр клиента, настроенного AzureAIChatCompletionsModel для подключения к развернутой модели, используя ключ API для аутентификации. Этот клиент выступает в качестве интерфейса API вывода модели.

Ссылки:

• Интеграция LangChain с Azure AI
• Обзор API вывода модели

Если конечная точка поддерживает Microsoft Entra ID, используйте следующий код для создания клиента:

import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
)

Если вы планируете использовать асинхронные вызовы, используйте асинхронную версию учетных данных:

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="Mistral-Large-3",
)

Если конечная точка обслуживает одну модель (например, бессерверные развертывания API), не включайте model параметр:

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_AI_CREDENTIAL"],
)

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

Проверьте подключение клиента с помощью простого вызова:

response = model.invoke("Say hello")
print(response.content)

Что это делает: Вызывает модель с простым запросом на проверку подлинности и подключения. Ожидаемые выходные данные: приветственное сообщение модели (например, "Hello! Как я могу помочь вам сегодня?").

Ссылки:

• Интерфейс Runnable LangChain

Использование моделей завершения чата

Используйте модель напрямую. ChatModels — это экземпляр интерфейса LangChain Runnable , который предоставляет стандартный способ взаимодействия с ними. Чтобы вызвать модель, передайте в метод список сообщений invoke .

from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="Translate the following from English into Italian"),
    HumanMessage(content="hi!"),
]

model.invoke(messages)

Что делает этот фрагмент кода: Демонстрирует передачу списка HumanMessage и SystemMessage объектов методу модели invoke() для создания ответа.

Ссылки:

• Сообщения LangChain
• Интерфейс Runnable LangChain

Составление операций как требуется в цепочки. Используйте шаблон подсказки для перевода предложений.

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

system_template = "Translate the following into {language}:"
prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

Эта цепочка принимает входные данные language и text. Теперь создайте средство синтаксического анализа выходных данных:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Что делает этот фрагмент кода: Создает объект StrOutputParser , который преобразует выходные данные модели в строковый формат, отрезая все дополнительные метаданные.

Ссылки:

• Средства синтаксического анализа выходных данных LangChain

Объедините шаблон, модель и синтаксический анализатор выходных данных, используя оператор пайпа (|):

chain = prompt_template | model | parser

Инициировать цепочку, предоставив значения language и text, используя метод invoke.

chain.invoke({"language": "italian", "text": "hi"})

Объединение нескольких LLM

Так как модели в Foundry предоставляют общий API вывода моделей, можно создать цепочку нескольких операций LLM и выбрать модель, подходящую для каждого шага.

В следующем примере создается два клиента модели: один производитель и один проверятель. Чтобы четко определить различие, используйте конечную точку с несколькими моделями, например API вывода моделей , и передайте model параметр в большую модель для создания и небольшой модели для проверки. Для производства содержимого обычно требуется более крупная модель, а проверка может использовать меньшую.

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

producer = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

verifier = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="mistral-small",
)

Что делает этот фрагмент кода: Создает экземпляры двух отдельных AzureAIChatCompletionsModel клиентов: один используется Mistral-Large-3 для создания контента, а другой используется Mistral-Small для проверки, демонстрируя выбор различных моделей для различных задач.

Ссылки:

• Интеграция LangChain Azure ИИ

В следующем примере создается стихотворение, написанное городским поэтом:

from langchain_core.prompts import PromptTemplate

producer_template = PromptTemplate(
    template="You are an urban poet, your job is to come up \
             verses based on a given topic.\n\
             Here is the topic you have been asked to generate a verse on:\n\
             {topic}",
    input_variables=["topic"],
)

verifier_template = PromptTemplate(
    template="You are a verifier of poems, you are tasked\
              to inspect the verses of poem. If they consist of violence and abusive language\
              report it. Your response should be only one word either True or False.\n \
              Here is the lyrics submitted to you:\n\
              {input}",
    input_variables=["input"],
)

Что делает этот фрагмент кода: Создает шаблон запроса и связывает его с клиентом модели producer для формирования творческого контента (в данном случае стихотворения).

Соберите части цепью:

chain = producer_template | producer | parser | verifier_template | verifier | parser

Что делает этот фрагмент кода: Объединяет созданное стихотворение с помощью verifier модели для валидации или рецензирования созданного содержимого, демонстрируя рабочий процесс "производитель-проверяющий".

Предыдущая цепочка возвращает только выходные данные verifier шага. Чтобы получить доступ к промежуточному результату, созданному producer, используйте RunnablePassthrough для вывода этого промежуточного результата.

from langchain_core.runnables import RunnablePassthrough, RunnableParallel

generate_poem = producer_template | producer | parser
verify_poem = verifier_template | verifier | parser

chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verification=RunnablePassthrough() | verify_poem)

Вызовите цепочку invoke с помощью метода:

chain.invoke({"topic": "living in a foreign country"})

Что делает этот фрагмент кода: Вызывает полную цепочку производителя-верификатора с вводом темы, возвращая как созданное содержимое, так и результат проверки. Ожидаемый вывод: объект JSON с ключами poem и verification, содержащими созданное стихотворение и ответ проверки.

Ссылки:

• LangChain Runnables

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

Создайте клиент внедрения таким же образом. Задайте переменные среды, чтобы указать модель внедрения:

export AZURE_INFERENCE_ENDPOINT="<your-model-endpoint-goes-here>"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

Создайте клиент:

import os
from langchain_azure_ai.embeddings import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="text-embedding-3-large",
)

Что делает этот фрагмент кода: Создает экземпляр клиента эмбеддинга, используя AzureAIEmbeddingsModel для преобразования текста в векторные представления, которые можно использовать для семантического поиска и сравнения по схожести.

Ссылки:

• Внедрение LangChain

Используйте векторное хранилище в памяти:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Что делает этот фрагмент кода: Создает векторное хранилище (InMemoryVectorStore) в памяти, которое сохраняет векторы для быстрых операций поиска сходства.

Ссылки:

• Хранилища векторов LangChain

Добавление документов:

from langchain_core.documents import Document

document_1 = Document(id="1", page_content="foo", metadata={"baz": "bar"})
document_2 = Document(id="2", page_content="thud", metadata={"bar": "baz"})

documents = [document_1, document_2]
vector_store.add_documents(documents=documents)

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

Ссылки:

• Хранилища векторов LangChain

Поиск по подобию:

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

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

Использование моделей OpenAI Azure

При использовании моделей OpenAI Azure с пакетом langchain-azure-ai используйте следующий формат конечной точки:

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

llm = AzureAIChatCompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/v1",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="gpt-4o"
)

Что делает этот фрагмент: Создает экземпляр клиента, специально настроенного для моделей Azure OpenAI, используя формат конечной точки Azure OpenAI. Параметр endpoint указывает на ресурс OpenAI Azure, а credential использует ключ API, хранящийся в переменной среды.

Ссылки:

• Интеграция LangChain с Azure AI

Отладка и устранение неполадок

Если необходимо выполнить отладку приложения и понять запросы, отправленные в модели в Foundry, используйте возможности отладки интеграции:

Сначала настройте логирование на нужный уровень:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

Что делает этот фрагмент кода: настраивает журналирование в Python на уровне DEBUG, чтобы получить подробную информацию о HTTP-запросах и ответах между LangChain и API вывода модели.

Ссылки:

• модуль ведения журнала Python

Чтобы просмотреть полезные данные запроса, передайте logging_enable=True в client_kwargs при создании экземпляра клиента.

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
    client_kwargs={"logging_enable": True},
)

Что делает этот фрагмент кода: Создает клиент с включенным ведением журнала для захвата и отображения подробных данных запроса/ответа, полезных для отладки взаимодействий API.

Используйте клиент как обычно в коде.

Трассировка

Используйте трассировку в Foundry, создав трассировщик. Журналы хранятся в приложение Azure Insights и могут запрашиваться в любое время с помощью Azure Monitor или портала Foundry. Каждый концентратор ИИ имеет связанный экземпляр приложение Azure Insights.

Получите "строка подключения" для инструментирования

Вы можете настроить приложение для отправки телеметрии в приложение Azure Insights с помощью любого из следующих методов:

1. Используйте строку подключения для приложение Azure Insights непосредственно.

   1. Перейдите на портал Foundry и выберите Отслеживание.

   2. Выберите "Управление источником данных". На этом экране вы увидите экземпляр, связанный с проектом.

   3. Скопируйте значение строки подключения и задайте для нее следующую переменную:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Используйте Microsoft Foundry SDK и endpoint Foundry Project:

   1. Убедитесь, что пакет azure-ai-projects установлен в вашей среде.

   2. Перейдите на портал Foundry.

   3. Скопируйте URL-адрес конечной точки проекта Foundry и задайте его в следующем коде:

      from azure.ai.projects import AIProjectClient
      from azure.identity import DefaultAzureCredential
      
      project_client = AIProjectClient(
          credential=DefaultAzureCredential(),
          endpoint="<your-foundry-project-endpoint-url>",
      )
      
      application_insights_connection_string = project_client.telemetry.get_application_insights_connection_string()
      

Узнайте больше о том, как визуализировать трассировки и управлять ими.

Дальнейшие действия

• Разработка приложений с помощью LlamaIndex
• Визуализация трассировок и управление ими в Foundry
• Использование моделей Foundry
• Справочник. API вывода модели