使用 LangChain 和 Azure AI Foundry 开发应用程序

LangChain 是一个开发生态系统，能帮助开发人员尽可能轻松地构建应用程序。 生态系统由多个组件组成。 其中大多数组件可以单独使用，因此，你可以挑选自己最喜欢的组件。

部署到 Azure AI Foundry 的模型可以通过两种方式与 LangChain 配合使用：

• 使用 Azure AI Foundry 模型 API： 部署到 Azure AI Foundry 的所有模型都支持 Foundry 模型 API，该 API 提供了一组通用的功能，可用于目录中的大部分模型。 该 API 的好处是，由于它对于所有模型都是相同的，因此从一个模型更改到另一个模型就像更改正在使用的模型部署一样简单。 不需要在代码中进行其他更改。 使用 LangChain 时，安装扩展 langchain-azure-ai。

• 使用特定于模型提供商的 API：某些模型（例如 OpenAI、Cohere 或 Mistral）为 LangChain 提供了其自己的一组 API 和扩展。 这些扩展可能包括模型支持的特定功能，因此，如果想要利用它们，则适用。 使用 LangChain 时，安装特定于要使用的模型的扩展，如 langchain-openai 或 langchain-cohere。

本教程介绍如何使用包 langchain-azure-ai 通过 LangChain 生成应用程序。

先决条件

若要运行本教程，需要：

• 一个 Azure 订阅。

• 已部署一个支持 Foundry 模型 API 的模型部署。 在此示例中，我们使用 Mistral-Large-2407中的 部署。

• 已安装 Python 3.9 或更高版本，包括 pip。

• 已安装 LangChain。 可以使用以下方法执行此操作：

  pip install langchain-core
  

• 在此示例中，我们将使用 Foundry 模型 API，因此我们安装以下包：

  pip install -U langchain-azure-ai
  

配置环境

若要使用部署在 Azure AI Foundry 门户中的 LLM，你需要终结点和凭据来连接到它。 请按照以下步骤从想要使用的模型中获取所需的信息：

1. 转到 Azure AI Foundry。

2. 打开部署模型的项目（如果尚未打开）。

3. 转到“模型 + 终结点”，并根据先决条件选择已部署的模型。

4. 复制终结点 URL 和密钥。

   

   小窍门

   如果模型部署了 Microsoft Entra ID 支持，则不需要密钥。

在这种情况下，我们将终结点 URL 和密钥都放在以下环境变量中：

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

配置后，使用init_chat_model创建一个客户端以连接聊天模型。 对于 Azure OpenAI 模型，请按照使用 Azure OpenAI 模型中的说明来配置客户端。

from langchain.chat_models import init_chat_model

llm = init_chat_model(model="mistral-large-2407", model_provider="azure_ai")

还可以直接使用该类 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-2407",
)

如果终结点支持 Microsoft Entra ID，则可以使用以下代码创建客户端：

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

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="mistral-large-2407",
)

如果计划使用异步调用，最佳做法是使用异步版本来获取凭据：

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

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="mistral-large-2407",
)

如果终结点提供一个模型，例如标准部署，则无需指示 model 参数：

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

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

使用聊天补全模型

首先，让我们直接使用模型。 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)

还可以根据需要在 链中组合操作。 现在，让我们使用提示模板来翻译句子：

from langchain_core.output_parsers import StrOutputParser

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

从提示模板中可以看出，此链具有 language 和 text 输入。 现在，让我们创建一个输出分析程序：

from langchain_core.prompts import ChatPromptTemplate
parser = StrOutputParser()

现在，我们可以使用垂直条 (|) 运算符将上面的模板、模型和输出分析程序组合起来：

chain = prompt_template | model | parser

若要调用链，请识别所需的输入并使用 invoke 方法提供值：

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

'ciao'

将多个 LLM 链接在一起

部署到 Azure AI Foundry 的模型支持 Foundry 模型 API，这是所有模型的标准。 根据每个模型的功能链接多个 LLM 操作，这样就可以根据功能优化合适的模型。

在以下示例中，我们将创建两个模型客户端。 一个是生成者，另一个是验证者。 为了明确对其进行区分，我们使用多模型终结点（例如 Foundry 模型 API），因此我们传递参数 model 来使用 Mistral-Large 和 Mistral-Small 模型，体现了“生成内容比验证内容更复杂”这一事实。

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-2407",
)

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

以下示例可生成一首由城市诗人写的诗：

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"],
)

现在让我们链接这些片段：

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

上一个链仅返回步骤 verifier 的输出。 由于我们想要访问 producer 生成的中间结果，因此在 LangChain 中，需要使用 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"})

{
  "peom": "...",
  "verification: "false"
}

使用嵌入模型

可以按照创建 LLM 客户端的方式连接到嵌入模型。 在以下示例中，我们将环境变量设置为现在指向嵌入模型：

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

然后创建客户端：

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",
)

以下示例显示了使用内存中的向量存储的简单示例：

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

让我们添加一些文档：

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)

让我们通过相似度进行搜索：

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

使用 Azure OpenAI 模型

如果您使用带有langchain-azure-ai包的 Azure OpenAI 模型，请使用以下 URL。

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

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

调试和故障排除

如果需要调试应用程序并了解发送到 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)

若要查看请求的有效负载，请在实例化客户端时将参数 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-2407",
    client_kwargs={"logging_enable": True},
)

像往常一样在代码中使用客户端。

追踪

可以通过创建跟踪器来使用 Azure AI Foundry 中的跟踪功能。 日志存储在 Azure Application Insights 中，可以随时使用 Azure Monitor 或 Azure AI Foundry 门户进行查询。 每个 AI 中心都有一个与之关联的 Azure Application Insights。

获取检测连接字符串

可以将应用程序配置为通过以下方式之一将遥测数据发送到 Azure Application Insights：

1. 直接使用用于连接到 Azure Application Insights 的连接字符串：

   1. 转到 Azure AI Foundry 门户并选择“跟踪”。

   2. 选择“管理数据源”。 在此屏幕中，可以看到与项目关联的实例。

   3. 复制“连接字符串”中的值并将其设置到以下变量：

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. 使用 Azure AI Foundry SDK 和项目连接字符串。

   1. 确保已在环境中安装了 azure-ai-projects 包。

   2. 转到 Azure AI Foundry 门户。

   3. 复制项目的连接字符串并使用以下代码设置它：

      from azure.ai.projects import AIProjectClient
      from azure.identity import DefaultAzureCredential
      
      project_client = AIProjectClient.from_connection_string(
          credential=DefaultAzureCredential(),
          conn_str="<your-project-connection-string>",
      )
      
      application_insights_connection_string = project_client.telemetry.get_connection_string()
      

为 Azure AI Foundry 配置跟踪

以下代码创建一个连接到 Azure AI Foundry 中项目后面的 Azure Application Insights 的跟踪器。 请注意，参数 enable_content_recording 设置为 True。 这样就可以捕获整个应用程序以及中间步骤的输入和输出。 这在调试和生成应用程序时很有帮助，但可能需要在生产环境中禁用它。 它默认为环境变量 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED：

from langchain_azure_ai.callbacks.tracers import AzureAIInferenceTracer

tracer = AzureAIInferenceTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

若要使用链配置跟踪，请将 invoke 操作中的 config 值指示为回调：

chain.invoke({"topic": "living in a foreign country"}, config={"callbacks": [tracer]})

若要配置链本身以进行跟踪，请使用 .with_config() 方法：

chain = chain.with_config({"callbacks": [tracer]})

然后像往常一样使用 invoke() 方法：

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

查看跟踪

若要查看跟踪，请：

1. 转到 Azure AI Foundry 门户。

2. 导航到“跟踪”部分。

3. 识别你已创建的跟踪。 显示跟踪可能需要几秒钟的时间。

   

详细了解如何可视化和管理跟踪。

后续步骤

• 使用 LlamaIndex 开发应用程序
• 在 Azure AI Foundry 中可视化和管理跟踪
• 使用 Azure AI Foundry 模型
• 参考：Foundry 模型 API