教學課程：第 1 部分 - 使用 Azure AI Foundry SDK 設定專案與開發環境，以建置自定義知識擷取（RAG）應用程式

發行項
12/18/2024

在本教學課程中，您會使用 Azure AI Foundry SDK（和其他連結庫）為您的零售公司建立、設定及評估名為 Contoso Trek 的聊天應用程式。您的零售公司專門銷售戶外露營裝備和服裝。聊天應用程式應該會回答您的產品和服務相關問題。例如，聊天應用程式可以回答諸如「哪種帳篷最防水？」或「哪種睡袋最適合寒冷天氣？」等問題。

本教學課程是三部分教學課程的第一部分。第一部分可讓您準備好在第二部分中撰寫程序代碼，並在第三部分中評估聊天應用程式。在這個部分中，您要：

建立專案
建立 Azure AI 搜尋索引
安裝 Azure CLI 並登入
安裝 Python 和套件
將模型部署至您的專案
設定環境變數

如果您已完成其他教學課程或快速入門，您可能已經建立了本教學課程所需的一些資源。如果您已經完成的話，即可放心地跳過這裡的這些步驟。

本教學課程是三部分教學課程的第一部分。

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

必要條件

具有有效訂用帳戶的 Azure 帳戶。如果您沒有帳戶，可免費建立帳戶。

建立專案

若要在 Azure AI Foundry 中建立專案，請遵循下列步驟：

移至 Azure AI Foundry 的首頁。
選取 [+ 建立專案]。
輸入專案名稱。將所有其他設定保留為預設值。
專案會在中樞中建立。如果您看到 建立新的中樞 ，請選取它並指定名稱。然後選取下一步。（如果您沒有看到 建立新的中樞，別擔心;這是因為正在為您建立新的中樞。
選取 [ 自定義 ] 以指定中樞的屬性。
使用您想要的任何值，但區域除外。建議您針對本教學課程系列使用 美國東部 2 或 瑞典中部 。
選取 [下一步]。
選取建立專案。

部署模型

您需要兩個模型來建置 RAG 型聊天應用程式：Azure OpenAI 聊天模型 (gpt-4o-mini) 和 Azure OpenAI 內嵌模型 (text-embedding-ada-002)。在 Azure AI Foundry 專案中部署這些模型，並針對每個模型使用這組步驟。

這些步驟會將模型從 Azure AI Foundry 入口網站模型目錄部署到即時端點：

在左側瀏覽窗格中，選取 [模型目錄]。
從模型清單中選取 gpt-4o-mini 模型。您可以使用搜尋列來尋找它。
在 [模型詳細數據] 頁面上，選取 [ 部署]。
保留預設 的部署名稱。選取 [ 部署]。或者，如果您的區域無法使用模型，則會為您選取不同的區域，並聯機到您的專案。在此情況下，請選取 [ 連線並部署]。

部署 gpt-4o-mini 之後，請重複步驟來部署 text-embedding-ada-002 模型。

建立 Azure AI 搜尋服務

此應用程式的目標是讓模型以您的自訂資料作為基礎來做出回應。搜尋索引可用來根據使用者的問題擷取相關文件。

您需要 Azure AI 搜尋服務和連線，才能建立搜尋索引。

注意

建立 Azure AI 搜尋服務和後續的搜尋索引會有相關成本。您可以在建立頁面上查看有關 Azure AI 搜尋服務之定價和定價層的詳細資料，先確認成本再建立資源。

如果您已經有 Azure AI 搜尋服務，即可跳到下一節。

否則，您可以使用 Azure 入口網站建立 Azure AI 搜尋服務。

提示

此步驟是您在本教學課程系列中使用 Azure 入口網站的唯一時間。其餘的工作是在 Azure AI Foundry 入口網站或您的本機開發環境中完成。

在入口網站中建立 Azure AI 搜尋服務。
選取您的資源群組和執行個體詳細資料。您可以在此頁面查看定價和定價層的詳細資料。
繼續執行精靈，然後選取 [檢閱 + 指派] 以建立資源。
確認 Azure AI 搜尋服務的詳細資料，包括預估成本。
選取 [建立] 以建立 Azure AI 搜尋服務。

將 Azure AI 搜尋服務連結到您的專案

如果您的項目中已經有 Azure AI 搜尋連線，您可以跳到安裝 Azure CLI 並登入。

在 Azure AI Foundry 入口網站中，檢查 Azure AI 搜尋連線的資源。

在 Azure AI Foundry 中，移至您的項目，然後從左窗格中選取 [管理中心 ]。
在 [已連線的資源] 區段中，查看您是否有 Azure AI 搜尋類型的連線。
如果您有 Azure AI 搜尋連線，您可以直接跳到下一節。
否則，請選取 [新增連線]，然後選取 [Azure AI 搜尋服務]。
在選項中尋找您的 Azure AI 搜尋服務，然後選取 [新增連線]。
使用 API 金鑰 進行驗證。

重要

不建議用於生產環境的 API 金鑰選項。若要選取並使用建議的 Microsoft Entra ID 驗證選項，您也必須設定 Azure AI 搜尋服務的存取控制。將搜尋索引數據參與者和 Search Service 參與者角色指派給您的用戶帳戶。如需詳細資訊，請參閱在 Azure AI Foundry 入口網站中使用角色和角色型訪問控制連線到 Azure AI 搜尋服務。
請選取新增連線。

安裝 Azure CLI 並登入

您安裝 Azure CLI 並從您的本機開發環境登入，讓您可以使用您的使用者認證來呼叫 Azure OpenAI 服務。

在大部分情況下，您可以使用下列命令，從終端機安裝 Azure CLI：

winget install -e --id Microsoft.AzureCLI

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

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 或更高版本，您可以使用下列命令來建立虛擬環境：

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

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

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

啟用 Python 環境表示，當您命令列執行 python 或 pip，將會使用應用程式的 .venv 資料夾中所包含的 Python 解譯器。

注意

您可以使用 deactivate 命令來結束 Python 虛擬環境，並可以稍後視需要重新啟用它。

安裝套件

安裝 azure-ai-projects（預覽）和 azure-ai-inference （預覽），以及其他必要的套件。

首先，在項目資料夾中建立名為 requirements.txt 的檔案。將下列套件新增至檔案：

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

安裝必要的套件：
```
pip install -r requirements.txt
```

建立協助程式腳本

為您的工作建立資料夾。在此資料夾中建立名為 config.py 的 檔案。本協助程式腳本會在教學課程系列接下來的兩個部分中使用。新增下列程式碼：

# 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。
如果您還沒有搜尋索引，請保留的值「example-index」。。AISEARCH_INDEX_NAME 在本教學課程的第 2 部分中，您將使用此名稱建立索引。如果您先前已建立想要改用的搜尋索引，請更新值以符合該搜尋索引的名稱。
如果您在部署模型時變更模型的名稱，請更新檔案中的 .env 值，以符合您所使用的名稱。

提示

如果您正在 VS Code 中工作，請在檔案中 .env 儲存變更之後關閉並重新開啟終端機視窗。

警告

請確定您的 .env 檔案位於檔案 .gitignore 中，以免不小心將它簽入 Git 存放庫。

清除資源

為了避免產生不必要的 Azure 費用，如果您不再需要在本教學課程中建立的資源，則應加以刪除。若要管理資源，您可以使用 Azure 入口網站。

但是，如果您要在本教學課程系列的下一個部分建置聊天應用程式，則請勿將其刪除。

後續步驟

在本教學課程中，您會設定使用 Azure AI SDK 建置自定義聊天應用程式所需的所有專案。在本教學課程系列的下一個部分中，您會建置自定義應用程式。

第 2 部分：使用 Azure AI SDK 建置自定義聊天應用程式

共用方式為

教學課程：第 1 部分 - 使用 Azure AI Foundry SDK 設定專案與開發環境，以建置自定義知識擷取（RAG）應用程式

必要條件

建立專案

部署模型

建立 Azure AI 搜尋服務

將 Azure AI 搜尋服務連結到您的專案

安裝 Azure CLI 並登入

建立新的 Python 環境

如有需要，請安裝 Python

建立虛擬環境

安裝套件

建立協助程式腳本

設定環境變數

清除資源

後續步驟

意見反應

其他資源

共用方式為

教學課程：第 1 部分 - 使用 Azure AI Foundry SDK 設定專案與開發環境，以建置自定義知識擷取 （RAG） 應用程式

必要條件

建立專案

部署模型

建立 Azure AI 搜尋服務

將 Azure AI 搜尋服務連結到您的專案

安裝 Azure CLI 並登入

建立新的 Python 環境

如有需要，請安裝 Python

建立虛擬環境

安裝套件

建立協助程式腳本

設定環境變數

清除資源

後續步驟

意見反應

其他資源

教學課程：第 1 部分 - 使用 Azure AI Foundry SDK 設定專案與開發環境，以建置自定義知識擷取（RAG）應用程式