你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

教程：第 1 部分 - 使用 Azure AI Foundry SDK 设置项目和开发环境以生成自定义知识检索 (RAG) 应用

在本教程中，我们使用 Azure AI Foundry SDK（以及其他库）为零售公司 Contoso Trek 生成、配置和评估聊天应用。 零售公司专门销售户外露营装备和服装。 聊天应用应该回答有关产品和服务的问题。 例如，聊天应用可以回答诸如“哪种帐篷最防水？”或“最适合寒冷天气的睡袋是什么？”之类的问题。

本教程是由三个部分构成的教程的第一部分。 第一部分可让你准备好在第二部分编写代码，并在第三部分评估聊天应用。 在本部分中，你将：

• 创建项目
• 创建 Azure AI 搜索索引
• 安装 Azure CLI 并登录
• 安装 Python 和包
• 将模型部署到项目中
• 配置环境变量

如果已完成其他教程或快速入门，则可能已经创建了本教程所需的一些资源。 如果有，可以跳过此处的步骤。

本教程是由三个部分构成的教程的第一部分。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

先决条件

• 具有活动订阅的 Azure 帐户。 如果你没有帐户，请免费创建一个。

创建项目

要在 Azure AI Foundry 中创建项目，请执行以下步骤：

1. 转到 Azure AI Foundry 的主页。
2. 选择“+ 创建项目”。
3. 输入项目的名称。 将所有其他设置留为默认值。
4. 项目在中心中创建。 如果看到“新建中心”，请选择它并指定名称。 然后选择下一步。 （如果未看到“新建中心”，请不要担心；这是因为正在为你创建一个新中心。）
5. 选择“自定义”以指定中心的属性。
6. 使用你想要的任何值（“区域”除外）。 对于本系列教程，建议对区域使用“美国东部 2”或“瑞典中部”。
7. 选择下一步。
8. 选择“创建项目”。

部署模型

需要使用两个模型来生成基于 RAG 的聊天应用：Azure OpenAI 聊天模型（gpt-4o-mini）和 Azure OpenAI 嵌入模型（text-embedding-ada-002）。 对每个模型使用此组步骤，以在 Azure AI Foundry 项目中部署这些模型。

这些步骤会将模型从 Azure AI Foundry 门户模型目录部署到实时终结点：

1. 从左侧导航窗格中选择“模型目录”。

2. 从模型列表中选择“gpt-4o-mini”模型。 可以使用搜索栏查找它。

   

3. 在模型详细信息页上，选择“部署”。

   

4. 保留默认部署名称。 选择“部署”。 或者，如果模型在你的区域中不可用，则会为你选择一个不同的区域并连接到你的项目。 在这种情况下，请选择“连接并部署”。

部署“gpt-4o-mini”后，重复步骤以部署“text-embedding-ada-002”模型。

创建 Azure AI 搜索服务

此应用程序的目标是在自定义数据中为模型答复提供基础。 搜索索引用于根据用户的问题检索相关文档。

需要使用 Azure AI 搜索服务和连接才能创建搜索索引。

注意

创建 Azure AI 搜索服务和后续搜索索引会产生相关费用。 可以在创建页面上查看有关 Azure AI 搜索服务定价和定价层的详细信息，以便在创建资源前确认成本。

如果已经拥有 Azure AI 搜索服务，则可跳至下一节。

否则，可以使用 Azure 门户创建 Azure AI 搜索服务。

提示

在本系列教程中，你仅会在此步骤中使用 Azure 门户。 其余工作是在 Azure AI Foundry 门户或你的本地开发环境中完成的。

1. 在 Azure 门户中创建 Azure AI 搜索服务。
2. 选择资源组和实例详细信息。 可在此页上查看有关定价和定价层的详细信息。
3. 继续执行向导，选择“查看 + 分配“可创建资源。
4. 确认 Azure AI 搜索服务的详细信息，包括估计成本。
5. 选择“创建”以创建 Azure AI 搜索服务。

将 Azure AI 搜索连接到项目

如果项目中已有 Azure AI 搜索连接，则可跳至安装 Azure AI 并登录。

在 Azure AI Foundry 门户中，检查连接到 Azure AI 搜索的资源。

1. 在 Azure AI Foundry 中，转到你的项目，然后从左侧窗格中选择“管理中心”。

2. 在“已连接资源”部分中，查看是否有 Azure AI 搜索类型的连接。

3. 如果有 Azure AI 搜索连接，则可以跳到下一部分。

4. 否则，选择“新建连接”，然后选择“Azure AI 搜索”。

5. 在选项中找到 Azure AI 搜索服务，然后选择“添加连接”。

6. 使用 API 密钥进行身份验证。

   重要

   不建议将“API 密钥”选项用于生产。 若要选择并使用建议的 Microsoft Entra ID 身份验证选项，还必须为 Azure AI 搜索服务配置访问控制。 为你的用户帐户分配“搜索索引数据参与者”和“搜索服务参与者”角色。 有关详细信息，请参阅使用角色连接到 Azure AI 搜索和 Azure AI Foundry 门户中基于角色的访问控制。

7. 选择“添加连接”。

安装 Azure CLI 并登录

你将安装 Azure CLI 并从你的本地开发环境登录，以便你可以使用你的用户凭据调用 Azure OpenAI 服务。

在大多数情况下，可以使用以下命令从终端安装 Azure CLI：

Windows

winget install -e --id Microsoft.AzureCLI

Linux

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

macOS

brew update && brew install azure-cli

如果这些命令不适用于特定操作系统或设置，则可以遵循说明如何安装 Azure CLI。

安装 Azure CLI 后，使用 az login 命令登录并使用浏览器登录：

az login

也可使用设备代码通过浏览器手动登录。

az login --use-device-code

创建新的 Python 环境

首先，需要创建一个新的 Python 环境，用于安装本教程所需的包。 请勿将包安装到你的全局 Python 安装中。 安装 Python 包时，应始终使用虚拟或 conda 环境，否则可能会中断 Python 的全局安装。

如果需要，请安装 Python

建议使用 Python 3.10 或更高版本，但至少需要 Python 3.8。 如果未安装合适的 Python 版本，则可以按照 VS Code Python 教程中的说明操作，这是在操作系统上安装 Python 的最简单方法。

创建虚拟环境

如果已安装 Python 3.10 或更高版本，则可以使用以下命令创建虚拟环境：

Windows

py -3 -m venv .venv
.venv\scripts\activate

Linux

python3 -m venv .venv
source .venv/bin/activate

macOS

python3 -m venv .venv
source .venv/bin/activate

激活 Python 环境意味着当通过命令行运行 python 或 pip 时，你将使用应用程序的 .venv 文件夹中包含的 Python 解释器。

注意

可以使用 deactivate 命令退出 python 虚拟环境，并在需要时重新激活它。

安装包

安装 azure-ai-projects（预览版）和 azure-ai-inference（预览版），以及其他必需的包。

1. 首先，在项目文件夹中创建名为 requirements.txt 的文件。 将以下包添加到文件：

   azure-ai-projects
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

2. 安装所需的包：

   pip install -r requirements.txt
   

创建 helper 脚本

为工作创建一个文件夹。 在此文件夹中创建一个名为 config.py 的文件。 此 helper 脚本将在教程系列的后续两个部分中使用。 添加以下代码：

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

配置环境变量

从代码调用 Azure OpenAI 服务需要项目连接字符串。 在本快速入门中，请将此值保存在 .env 文件中，该文件包含应用程序可以读取的环境变量。

创建 .env 文件并粘贴以下代码：

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

• 在 Azure AI Foundry 操场快速入门中创建的 Azure AI Foundry 项目中查找连接字符串。 打开项目，然后在“概述”页上找到连接字符串。 复制连接字符串并将其粘贴到 .env 文件中。

  

• 如果还没有搜索索引，请为 AISEARCH_INDEX_NAME 保留值“example-index”。 在本教程的第 2 部分中，你将使用此名称创建索引。 如果之前创建了想要改用的搜索索引，请更新此值以匹配该搜索索引的名称。

• 如果在部署模型时更改了模型名称，请更新 .env 文件中的值以匹配使用的名称。

提示

如果在 VS Code 中工作，在保存 .env 文件中的更改后，请关闭并重新打开终端窗口。

警告

请确保 .env 位于 .gitignore 文件中，以免将其意外签入 git 存储库中。

清理资源

为了避免产生不必要的 Azure 成本，如果不再需要在本快速入门中创建的资源，应该将其删除。 若要管理资源，可以使用 Azure 门户。

但如果你要在本教程系列的下一部分中生成聊天应用，先不要删除它们。

下一步

在本教程中，你将设置使用 Azure AI SDK 构建自定义聊天应用所需的所有内容。 在本教程系列的下一部分，你将生成自定义应用。

第 2 部分：使用 Azure AI SDK 生成自定义聊天应用