教學：第一部分 - 設定專案與開發環境，使用 Microsoft Foundry SDK 建立自訂知識檢索（RAG）應用程式

在這個教學中，你會設定使用Microsoft Foundry SDK打造自訂知識檢索（RAG）聊天應用程式所需的資源。 這是三部分教學系列的第一部分。 你在這裡建立資源，第二部分建置應用程式，第三部分評估。 在此部分中，您會：

如果你已經完成了其他教學或快速入門，可能已經製作了這個教學所需的部分資源。 如果你已經完成這些步驟，可以跳過它們。

先決條件

• 一個 Azure 帳戶，擁有有效訂閱並指定為 擁有者 或 參與者 角色。 如果您沒有帳戶，可免費建立帳戶。
• Microsoft Foundry：擁有者或貢獻者角色，負責創建專案。

建立中樞型專案

若要在 Microsoft Foundry 中建立中樞型專案，請遵循下列步驟：

1. 登入 Microsoft Foundry。 確定新鑄造廠的開關是關閉的。 這些步驟指的是 Foundry (傳統版)。

   

2. 接下來要做什麼取決於您的位置：

   • 如果您沒有任何現有專案：請依照快速入門：開始使用 Microsoft Foundry (部分內容可能是機器或 AI 翻譯) 中的步驟，建立您的第一個專案。

   • 如果您位於專案中：選取專案階層連結，然後選取 [建立新資源]。

     

   • 如果您不在專案中：選取右上角的 [新建] 以建立新的 Foundry 專案

     

3. 選取 [AI 中樞資源]，然後選取 [ 下一步]。

4. 輸入專案名稱。

5. 如果您有中樞，您會看到所選取最近使用的中樞。

   • 如果您有多個中樞的存取權，您可以從下拉式清單中選取不同的中樞。

   • 如果你想建立一個新的集會中心，請從下拉選單選擇 「建立一個新的集會中心 」。

     

6. 如果您沒有中樞，則會為您建立預設中樞。

7. 選取 ，創建。

部署模型

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

這些步驟將模型部署到Foundry入口 模型目錄中的即時端點：

1. 在左窗格中，選取 [模型目錄]。

2. 從模型清單中選取 gpt-4o-mini 模型。 您可以使用搜尋列來尋找它。

   

3. 在 [模型詳細數據] 頁面上，選取 [使用此模型]。

4. 保留預設 的部署名稱 ，並選擇 部署。 或者，如果模型在您的區域中無法使用，則會為您選取不同的區域，並連線到您的專案。 在此情況下，選取 [連線並部署]。

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

建立 Azure AI 搜尋服務

此應用程式的目標是將模型回應建立在您的自訂資料中。 搜尋索引會根據使用者的問題擷取相關文件。

你需要 Azure AI 搜尋服務和連線來建立搜尋索引。

如果你已經有 Azure AI 搜尋服務，請前往 下一節。

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

1. 在入口網站中建立 Azure AI 搜尋服務。
2. 選取您的資源群組和執行個體詳細資料。 請查看本頁的價格及價格層級。 建議在這個教學中使用基本版或更高的價格方案。
3. 繼續執行精靈，然後選取 [檢閱 + 指派] 以建立資源。
4. 確認您的 Azure AI 搜尋服務詳情，包括預估費用。
5. 選取 [建立] 以建立 Azure AI 搜尋服務。

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

如果你的專案已經有 Azure AI Search 連線，請到 安裝 Azure CLI 並登入。

在 Foundry 入口網站中，請查看是否有 Azure AI Search 相關的資源。

1. 在 Foundry 裡，進入你的專案，從左側窗格選擇 管理中心 。

2. 在 [已連線的資源] 區段中，查看您是否有類型為 Azure AI 搜尋服務的連線。

3. 如果你有 Azure AI 搜尋連線，可以跳過後續步驟。

4. 否則，請選取 [新增連線]，然後選取 [Azure AI 搜尋服務]。

5. 在選項中尋找您的 Azure AI 搜尋服務，然後選取 [新增連線]。

6. 針對 [驗證] 使用 [API 金鑰]。

   這很重要

   針對生產環境，不建議使用 [API 金鑰] 選項。 推薦的方法是使用 Microsoft Entra ID 認證，這需要搜尋 索引資料貢獻者（Search Index Data Contributor ）和 搜尋服務貢獻 者角色（在前置條件中設定）。 如需詳細資訊，請參閱使用角色連線到 Azure AI 搜尋服務。 在這個教學中，如果你想快速進行，API 金鑰 是可以接受的。 部署到生產環境前，請切換到 Entra ID。

7. 請選取新增連線。

建立新的 Python 環境

在您選擇的 IDE 中，為您的專案建立新的資料夾。 在該資料夾中開啟終端機視窗。

首先，建立一個新的 Python 環境。 請勿將套件安裝到您的全域 Python 安裝中。 安裝 Python 套件時，務必使用虛擬環境或 conda 環境。 否則，你可能會破壞 Python 的全域安裝。

如有需要，請安裝 Python

使用 Python 3.10 或更新版本，但至少需要 Python 3.9。 如果您沒有安裝適當的 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 直譯器。

安裝套件

安裝必要的套件。

1. 在你的專案資料夾裡建立一個名為 requirements.txt 的檔案。 將下列套件新增至檔案：

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

   References： Azure AI Projects client library， azure-ai-inference， python-dotenv.

2. 安裝必要的套件：

   pip install -r requirements.txt
   

設定環境變數

你的專案連接字串是從程式碼中呼叫 Microsoft Foundry Models 中的 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"

• 在你在 Foundry 遊樂場快速啟動中建立的 Foundry 專案中找到你的連接字串。 開啟專案，然後在 [概觀] 頁面上尋找連接字串。 複製連接字串並將它貼到 .env 檔案中。

  

• 如果您還沒有搜尋索引，請針對 AISEARCH_INDEX_NAME 保留值 "example-index"。 在本教學課程的第 2 部分中，您將使用此名稱建立索引。 如果您先前已建立想要改用的搜尋索引，請更新該值以符合該搜尋索引的名稱。

• 如果您在部署模型時變更模型的名稱，請更新 .env 檔案中的值，以符合您所使用的名稱。

安裝 Azure CLI 並登入

您安裝 Azure CLI 並從您的本機開發環境登入，讓您可以使用您的使用者認證，在 Microsoft Foundry 模型中呼叫 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 腳本。

驗證您的設定

透過快速測試確認您的環境設置正確：

import os
from azure.identity import DefaultAzureCredential
import azure.ai.projects

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

如果你看到 "Setup successful!"，你的 Azure 憑證和 SDK 設定正確。

參考資料： Azure AI Projects 客戶端庫， DefaultAzureCredential。

建立協助程式指令碼

為您的工作建立資料夾。 在這個資料夾裡建立一個名為 config.py 的檔案。 你會在接下來的兩部分教學中使用這個輔助腳本。 腳本會載入你的環境變數並初始化 Azure AI 專案客戶端。 新增下列程式碼：

# 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)

參考資料： AIProjectClient、 DefaultAzureCredential、 load_dotenv.

清理資源

為避免不必要的 Azure 成本，如果不再需要，請刪除你在教學中建立的資源。 若要管理資源，您可以使用 Azure 入口網站。

但如果你想在本 教學系列的下一部分建立聊天應用程式，請不要急著刪除它們。

後續步驟

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