使用 LlamaIndex 和 Azure AI Foundry 開發應用程式

2025-06-27

您將透過本文了解在 Azure AI Foundry 入口網站中，如何將 LlamaIndex 與從 Azure AI 模型目錄部署的模型搭配使用。

部署至 Azure AI Foundry 的模型可以以兩種方式與 LlamaIndex 一起使用：

使用 Azure AI 模型推斷 API： 部署至 Azure AI Foundry 的所有模型都支援模型推斷 API，其提供一組常見的功能，可用於目錄中大部分的模型。此 API 的優點是，由於對所有模型來說都相同，因此從一個模型變更為另一個模型，就像變更正在使用的模型部署一樣簡單。程式碼中不需要進一步的變更。使用 LlamaIndex 時，請安裝 llama-index-llms-azure-inference 和 llama-index-embeddings-azure-inference 延伸模組。
使用模型的提供者特定 API：部分模型 (例如 OpenAI、Cohere 或 Mistral) 提供一組自己的 API 和 LlamaIndex 延伸模組。這些延伸模組可能包含模型支援的特定功能，因此如果您想要利用這些功能，則適合使用。使用 llama-index 時，請安裝您想要使用之模型的特定延伸模組，例如 llama-index-llms-openai 或 llama-index-llms-cohere。

在此範例中，我們會使用 模型推斷 API。

先決條件

若要執行此教學課程，您需要：

Azure 訂用帳戶。
Azure AI 專案，如在 Azure AI Foundry 入口網站中建立專案中所述。
已部署支援模型推斷 API 的模型。在此範例中，我們使用 Mistral-Large 部署，但使用您偏好的任何模型。若要在 LlamaIndex 中使用內嵌功能，您需要內嵌模型，例如 cohere-embed-v3-multilingual。
- 您可以遵循將模型部署為標準部署中的指示。
已安裝 Python 3.8 或更新版本，包括 pip。
已安裝 LlamaIndex。您可以透過下列方式來完成：
```
pip install llama-index
```
在此範例中，我們會使用模型推斷 API，因此我們會安裝下列套件：
```
pip install -U llama-index-llms-azure-inference
pip install -U llama-index-embeddings-azure-inference
```
這很重要

使用 Foundry 模型服務需要版本 0.2.4 的 llama-index-llms-azure-inference 或 llama-index-embeddings-azure-inference。

建立環境

若要使用在 Azure AI Foundry 入口網站中部署的 LLM，您需要端點和認證才能加以連線。請遵循下列步驟，從您想要使用的模型取得所需的資訊：

小提示

因為您可以在 Azure AI Foundry 入口網站中自訂左窗格，因此您看到的項目可能會與這些步驟中顯示的不同。如果您沒有看到您要尋找的內容，請選取左窗格底部的 ... 更多。

移至 Azure AI Foundry。
請開啟模型部署所在的專案 (如果尚未開啟)。
移至 [模型 + 端點]，然後選取您部署的模型，如必要條件中所述。
複製端點 URL 和金鑰。

小提示

如果您的模型已使用 Microsoft Entra ID 支援部署，則不需要金鑰。

在此案例中，我們將端點 URL 和金鑰放在下列環境變數中：

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

設定好之後，請建立用戶端以連線到端點。

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
)

小提示

如果您的模型部署裝載於 Foundry Models 或 Azure AI Services 資源的 Azure OpenAI 中，請設定用戶端，如 Azure OpenAI 模型和 Foundry Models 服務所示。

如果您的端點提供多個模型，例如使用 Foundry Models 服務或 GitHub 模型，您必須指出 model_name 參數：

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model_name="mistral-large-2407",
)

或者，如果您的端點支援 Microsoft Entra ID，您可以使用下列程式碼來建立用戶端：

import os
from azure.identity import DefaultAzureCredential
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

備註

使用 Microsoft Entra ID 時，請確定端點是以該驗證方法部署，而且您具有加以叫用所需的權限。

如果您打算使用異步呼叫，最佳做法是針對認證使用異步版本：

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
)

Azure OpenAI 模型和 Foundry 模型服務

如果您使用 Azure OpenAI 或 Foundry Models 服務，請確定您至少有 LlamaIndex 整合的版本 0.2.4 。如果您需要選取特定的 api_version，請使用 api_version 參數。

針對 Foundry Models 服務，您必須傳遞 model_name 參數：

from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model_name="mistral-large-2407",
)

針對 Azure AI Foundry 中的 Azure OpenAI 模型：

from llama_index.llms.azure_inference import AzureAICompletionsModel

llm = AzureAICompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/deployments/<deployment-name>",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    api_version="2024-05-01-preview",
)

小提示

檢查部署所使用的 API 版本。使用錯誤或模型不支援的 api_version 會導致 ResourceNotFound 例外狀況。

推斷參數

您可以透過設定額外的參數，為使用此用戶端的所有作業設定推斷的執行方式。這有助於避免在每次呼叫模型時指出它們。

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    temperature=0.0,
    model_kwargs={"top_p": 1.0},
)

模型推斷 API (參考) 中不支援，但可在基礎模型中使用的參數，您可以使用 model_extras 引數。在下列範例中，正在傳遞參數 safe_prompt (僅適用於 Mistral 模型)。

llm = AzureAICompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    temperature=0.0,
    model_kwargs={"model_extras": {"safe_prompt": True}},
)

使用 LLM 模型

您可以在 LlamaIndex 中直接使用用戶端或設定程式碼所使用的模型。若要直接使用模型，請使用 chat 方法來進行聊天指示模型：

from llama_index.core.llms import ChatMessage

messages = [
    ChatMessage(
        role="system", content="You are a pirate with colorful personality."
    ),
    ChatMessage(role="user", content="Hello"),
]

response = llm.chat(messages)
print(response)

您也可以串流輸出：

response = llm.stream_chat(messages)
for r in response:
    print(r.delta, end="")

complete 方法仍適用於類型為 chat-completions 的模型。在那些案例中，您的輸入文字會使用 role="user" 轉換為訊息。

使用內嵌模型

正如同建立 LLM 用戶端的方式，您可以連線到內嵌模型。在下列範例中，我們將環境變數設定為現在指向內嵌模型：

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

接著，建立用戶端物件：

from llama_index.embeddings.azure_inference import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ['AZURE_INFERENCE_CREDENTIAL'],
)

下列範例會示範一個簡單的測試，以確認其運作正常：

from llama_index.core.schema import TextNode

nodes = [
    TextNode(
        text="Before college the two main things I worked on, "
        "outside of school, were writing and programming."
    )
]
response = embed_model(nodes=nodes)
print(response[0].embedding)

設定您的程式碼所使用的模型

您可以在使用 LlamaIndex 開發的程式碼中個別使用 LLM 或內嵌模型用戶端，或使用 Settings 選項來設定整個工作階段。設定工作階段具有讓您的所有程式碼針對所有作業使用相同模型的優點。

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model

不過，在某些案例中，您想要針對大部分作業使用一般模型，但針對特定工作使用特定模型。在這些情況下，為每個 LlamaIndex 組件設定您使用的 LLM 或嵌入式模型非常有用。在下列範例中，我們會提設定特定模型：

from llama_index.core.evaluation import RelevancyEvaluator

relevancy_evaluator = RelevancyEvaluator(llm=llm)

一般而言，您會使用這兩種策略的組合。

共用方式為