Microsoft Azure 文档
在 Azure AI 上使用 smolagents 构建智能体
并获得增强的文档体验
开始使用
在 Azure AI 上使用 smolagents 构建智能体
此示例展示了如何使用 smolagents
构建智能体,利用 Azure AI Foundry Hub 中 Hugging Face Collection 的大型语言模型 (LLM),并将其部署为 Azure ML 托管在线终结点。
本示例并非旨在深入探讨如何在 Azure AI 上部署大型语言模型 (LLM),而是侧重于如何使用它构建智能体。因此,强烈建议您阅读有关 Azure AI 部署的更多信息,例如“在 Azure AI 上部署大型语言模型 (LLM)”。
简而言之,Smolagents 是一个开源 Python 库,旨在让您极轻松地构建和运行智能体,只需几行代码。Azure AI Foundry 提供了一个统一平台,用于企业 AI 操作、模型构建和应用程序开发。Azure Machine Learning 是一种云服务,用于加速和管理机器学习 (ML) 项目生命周期。
本示例将特别部署来自 Hugging Face Hub 的 Qwen/Qwen2.5-Coder-32B-Instruct
(或在 AzureML 或 Azure AI Foundry 上查看),作为 Azure AI Foundry Hub 上的 Azure ML 托管在线终结点。
Qwen2.5-Coder 是 Code-Specific Qwen 大型语言模型(前身为 CodeQwen)的最新系列,与 CodeQwen1.5 相比,带来了以下改进:
- 在代码生成、代码推理和代码修复方面取得了显著进步。在强大的 Qwen2.5 的基础上,我们将训练令牌扩展到 5.5 万亿,包括源代码、文本-代码接地、合成数据等。Qwen2.5-Coder-32B 已成为当前最先进的开源代码 LLM,其编码能力与 GPT-4o 相当。
- 为代码智能体等实际应用提供了更全面的基础。不仅增强了编码能力,还在数学和通用能力方面保持了其优势。
- 支持长达 128K 令牌的长上下文。
有关更多信息,请务必查看 Hugging Face Hub 上的其模型卡。
请注意,您可以选择 Hugging Face Hub 上任何启用“部署到 AzureML”选项的 LLM,或者直接选择 Azure ML 或 Azure AI Foundry Hub 模型目录中“HuggingFace”集合下的任何 LLM(请注意,对于 Azure AI Foundry,Hugging Face Collection 仅适用于基于 Hub 的项目)。
先决条件
要运行以下示例,您需要满足以下先决条件,或者,您也可以在Azure Machine Learning 教程:创建入门所需的资源中阅读更多相关信息。
- 具有活动订阅的 Azure 帐户。
- 已安装并登录 Azure CLI。
- 适用于 Azure CLI 的 Azure 机器学习扩展。
- 一个 Azure 资源组。
- 基于 Azure AI Foundry Hub 的项目。
有关更多信息,请按照 为 Azure AI 配置 Microsoft Azure 中的步骤操作。
设置和安装
在本示例中,将使用 Azure Machine Learning SDK for Python 来创建终结点和部署,以及调用已部署的 API。同时,您还需要安装 azure-identity
,以便通过 Python 使用 Azure 凭据进行身份验证。
%pip install azure-ai-ml azure-identity --upgrade --quiet
更多信息请参见 适用于 Python 的 Azure 机器学习 SDK。
然后,为了方便起见,建议设置以下环境变量,因为它们将在示例中用于 Azure ML 客户端,因此请务必根据您的 Microsoft Azure 帐户和资源更新并设置这些值。
%env LOCATION eastus %env SUBSCRIPTION_ID <YOUR_SUBSCRIPTION_ID> %env RESOURCE_GROUP <YOUR_RESOURCE_GROUP> %env AI_FOUNDRY_HUB_PROJECT <YOUR_AI_FOUNDRY_HUB_PROJECT>
最后,您还需要定义终结点和部署名称,因为它们也将在整个示例中使用。
请注意,终结点名称在每个区域内必须是全局唯一的,也就是说,即使您没有在订阅下运行任何以此命名的终结点,如果该名称已被其他 Azure 客户预留,您也将无法使用相同的名称。建议添加时间戳或自定义标识符,以防止在尝试部署已锁定/预留名称的终结点时遇到 HTTP 400 验证问题。此外,终结点名称的长度必须在 3 到 32 个字符之间。
import os
from uuid import uuid4
os.environ["ENDPOINT_NAME"] = f"qwen-coder-endpoint-{str(uuid4())[:8]}"
os.environ["DEPLOYMENT_NAME"] = f"qwen-coder-deployment-{str(uuid4())[:8]}"
向 Azure ML 进行身份验证
首先,您需要通过 Azure ML Python SDK 向 Azure AI Foundry Hub 进行身份验证,该 SDK 将用于将 Qwen/Qwen2.5-Coder-32B-Instruct
部署为 Azure AI Foundry Hub 中的 Azure ML 托管在线终结点。
在标准 Azure ML 部署中,您需要使用 Azure ML 工作区作为 workspace_name
来创建 MLClient
,而在 Azure AI Foundry 中,您需要将 Azure AI Foundry Hub 名称作为 workspace_name
提供,这将把终结点也部署到 Azure AI Foundry 中。
import os
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential
client = MLClient(
credential=DefaultAzureCredential(),
subscription_id=os.getenv("SUBSCRIPTION_ID"),
resource_group_name=os.getenv("RESOURCE_GROUP"),
workspace_name=os.getenv("AI_FOUNDRY_HUB_PROJECT"),
)
创建和部署 Azure AI 终结点
在创建托管在线终结点之前,您需要构建模型 URI,其格式如下:azureml://registries/HuggingFace/models/<MODEL_ID>/labels/latest
,其中 MODEL_ID
不是 Hugging Face Hub ID,而是它在 Azure 上的名称,如下所示:
model_id = "Qwen/Qwen2.5-Coder-32B-Instruct"
model_uri = (
f"azureml://registries/HuggingFace/models/{model_id.replace('/', '-').replace('_', '-').lower()}/labels/latest"
)
model_uri
要检查 Hugging Face Hub 中的模型是否在 Azure 中可用,您应该阅读支持的模型。如果不可用,您随时可以在 Azure 上的 Hugging Face 集合中请求添加模型)。
然后,您需要通过 Azure ML Python SDK 创建 ManagedOnlineEndpoint,如下所示。
Hugging Face Collection 中的每个模型都由高效的推理后端提供支持,每个模型都可以在各种实例类型上运行(如支持的硬件中所列)。由于模型和推理引擎需要 GPU 加速实例,您可能需要根据管理和增加 Azure Machine Learning 资源的配额和限制来请求增加配额。
from azure.ai.ml.entities import ManagedOnlineEndpoint, ManagedOnlineDeployment
endpoint = ManagedOnlineEndpoint(name=os.getenv("ENDPOINT_NAME"))
deployment = ManagedOnlineDeployment(
name=os.getenv("DEPLOYMENT_NAME"),
endpoint_name=os.getenv("ENDPOINT_NAME"),
model=model_uri,
instance_type="Standard_NC40ads_H100_v5",
instance_count=1,
)
client.begin_create_or_update(endpoint).wait()
在 Azure AI Foundry 中,终结点只有在部署创建后才会在“我的资产 -> 模型 + 终结点”选项卡中列出,不像 Azure ML 那样,即使终结点不包含任何活动或正在进行的部署也会显示。
client.online_deployments.begin_create_or_update(deployment).wait()
请注意,尽管 Azure AI 终结点的创建相对较快,但部署将花费更长时间,因为它需要在 Azure 上分配资源,所以预计需要大约 10-15 分钟,但也可能根据实例配置和可用性而花费更长时间。
部署完成后,您可以通过 Azure AI Foundry 或 Azure ML Studio 检查终结点详细信息、实时日志、如何使用终结点,甚至使用仍处于预览阶段的监控功能。欲了解更多信息,请访问Azure ML 托管在线终结点
使用 smolagents 构建智能体
现在 Azure AI 终结点已运行,您可以开始向其发送请求。由于有多种方法,但以下仅涵盖 OpenAI Python SDK 方法,您应该访问例如在 Azure AI 上部署大型语言模型 (LLM) 以查看不同的替代方案。
因此,构建智能体的步骤如下:
- 使用
smolagents
创建 OpenAI 客户端,通过smolagents.OpenAIServerModel
连接到正在运行的 Azure AI 终结点(请注意,smolagents
也公开了smolagents.AzureOpenAIServerModel
,但这用于通过 Azure 使用 OpenAI 的客户端,而不是连接到 Azure AI)。 - 定义智能体将有权访问的工具集,即带有
smolagents.tool
装饰器的 Python 函数。 - 创建
smolagents.CodeAgent
,利用部署在 Azure AI 上的代码-LLM,并添加先前定义的工具集,以便智能体可以在适当的时候使用这些工具,使用本地执行器(如果执行的代码敏感或未识别,则不推荐)。
创建 OpenAI 客户端
由于 Hugging Face 目录中的每个 LLM 都部署了暴露 OpenAI 兼容路由的推理引擎,因此您也可以通过 smolagents
利用 OpenAI Python SDK 向已部署的 Azure ML 终结点发送请求。
%pip install "smolagents[openai]" --upgrade --quiet
要将 OpenAI Python SDK 与 Azure ML 托管在线终结点一起使用,您需要首先检索
api_url
,带/v1
路由(包含 OpenAI Python SDK 将向其发送请求的v1/chat/completions
终结点)api_key
,它是 Azure AI 中的 API 密钥或 Azure ML 中的主密钥(除非使用专用的 Azure ML 令牌)
from urllib.parse import urlsplit
api_key = client.online_endpoints.get_keys(os.getenv("ENDPOINT_NAME")).primary_key
url_parts = urlsplit(client.online_endpoints.get(os.getenv("ENDPOINT_NAME")).scoring_uri)
api_url = f"{url_parts.scheme}://{url_parts.netloc}/v1"
或者,您也可以手动构建 API URL,如下所示,因为 URI 在每个区域中都是全局唯一的,这意味着在同一区域中只会有一个同名终结点。
api_url = f"https://{os.getenv('ENDPOINT_NAME')}.{os.getenv('LOCATION')}.inference.ml.azure.com/v1"
或者直接从 Azure AI Foundry 或 Azure ML Studio 中检索。
然后,您可以正常使用 OpenAI Python SDK,确保包含包含 Azure AI / ML 部署名称的额外标头 azureml-model-deployment
。
额外的标头将通过实例化客户端时 OpenAI Python SDK 的 default_headers
参数提供,通过 smolagents.OpenAIServerModel
的 client_kwargs
参数在 smolagents
中提供,该参数将把这些标头传播到底层的 OpenAI
客户端。
from smolagents import OpenAIServerModel
model = OpenAIServerModel(
model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
api_base=api_url,
api_key=api_key,
client_kwargs={"default_headers": {"azureml-model-deployment": os.getenv("DEPLOYMENT_NAME")}},
)
构建 Python 工具
smolagents
将用于构建智能体将利用的工具,以及构建 smolagents.CodeAgent
本身。以下工具将使用 smolagents.tool
装饰器定义,这将准备 Python 函数以用作 LLM 智能体中的工具。
请注意,函数签名应附带适当的类型提示以指导 LLM,以及清晰的函数名称,最重要的是,格式良好的文档字符串,说明函数的功能、参数、返回值以及可能引发的错误(如果适用)。
在这种情况下,将提供给智能体的工具如下:
世界时间 API -
get_time_in_timezone
:使用世界时间 API 获取给定位置的当前时间。维基百科 API -
search_wikipedia
:使用维基百科 API 获取维基百科条目的摘要。
在本例中,为简化起见,所使用的工具已从https://github.com/huggingface/smolagents/blob/main/examples/multiple_tools.py移植而来,因此所有功劳归于 smolagents
GitHub 仓库的原始作者和维护者。此外,只保留了用于查询世界时间 API 和维基百科 API 的工具,因为它们拥有慷慨的免费套餐,允许任何人免费使用,无需付费或创建帐户/API 令牌。
from smolagents import tool
世界时间 API - get_time_in_timezone
@tool
def get_time_in_timezone(location: str) -> str:
"""
Fetches the current time for a given location using the World Time API.
Args:
location: The location for which to fetch the current time, formatted as 'Region/City'.
Returns:
str: A string indicating the current time in the specified location, or an error message if the request fails.
Raises:
requests.exceptions.RequestException: If there is an issue with the HTTP request.
"""
import requests
url = f"http://worldtimeapi.org/api/timezone/{location}.json"
try:
response = requests.get(url)
response.raise_for_status()
data = response.json()
current_time = data["datetime"]
return f"The current time in {location} is {current_time}."
except requests.exceptions.RequestException as e:
return f"Error fetching time data: {str(e)}"
维基百科 API - search_wikipedia
@tool
def search_wikipedia(query: str) -> str:
"""
Fetches a summary of a Wikipedia page for a given query.
Args:
query: The search term to look up on Wikipedia.
Returns:
str: A summary of the Wikipedia page if successful, or an error message if the request fails.
Raises:
requests.exceptions.RequestException: If there is an issue with the HTTP request.
"""
import requests
url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{query}"
try:
response = requests.get(url)
response.raise_for_status()
data = response.json()
title = data["title"]
extract = data["extract"]
return f"Summary for {title}: {extract}"
except requests.exceptions.RequestException as e:
return f"Error fetching Wikipedia data: {str(e)}"
创建智能体
由于本例中部署在 Azure AI 上的 LLM 是代码专用 LLM,因此将使用 smolagents.CodeAgent
创建智能体,该智能体添加了相关的提示和解析功能,以便将 LLM 输出解释为代码。或者,也可以使用 smolagents.ToolCallingAgent
,它是一个工具调用智能体,这意味着给定的 LLM 应该具有工具调用能力。
然后,smolagents.CodeAgent
需要 model
和模型可以访问的 tools
集,然后通过 run
方法,您可以以自动方式利用智能体的所有潜力,无需手动干预;这样智能体将在需要时使用给定工具,以回答或满足您的初始请求。
from smolagents import CodeAgent
agent = CodeAgent(
tools=[
get_time_in_timezone,
search_wikipedia,
],
model=model,
stream_outputs=True,
)
agent.run(
"Could you create a Python function that given the summary of 'What is a Lemur?'"
" replaces all the occurrences of the letter E with the letter U (ignore the casing)"
)
# Summary for Lumur: Lumurs aru wut-nosud primatus of thu supurfamily Lumuroidua, dividud into 8 familius and consisting of 15 gunura and around 100 uxisting spucius. Thuy aru undumic to thu island of Madagascar. Most uxisting lumurs aru small, with a pointud snout, largu uyus, and a long tail. Thuy chiufly livu in truus and aru activu at night.
agent.run("What time is in Thailand right now? And what's the time difference with France?")
# The current time in Thailand is 5 hours ahead of the current time in France.
释放资源
完成 Azure AI 终结点/部署的使用后,您可以按如下方式删除资源,这意味着您将停止支付模型运行所在的实例费用,并且所有相关费用都将停止。
client.online_endpoints.begin_delete(name=os.getenv("ENDPOINT_NAME")).result()
结论
通过本示例,您学习了如何在基于 Azure AI Foundry Hub 的项目中部署 Azure ML 托管在线终结点,该终结点运行 Azure AI Foundry Hub / Azure ML 模型目录中的 Hugging Face Collection 中的开放模型,并利用它使用 smolagents
构建智能体,最后,如何停止和释放资源。
如果您对此示例有任何疑问、问题或疑问,请随时提出问题,我们将尽力提供帮助!
📍 在 GitHub 上找到完整示例 此处!