Tworzenie aplikacji za pomocą biblioteki LlamaIndex i Azure AI Foundry

2025-06-27

Z tego artykułu dowiesz się, jak używać usługi LlamaIndex z modelami wdrożonym z katalogu modeli usługi Azure AI w portalu Azure AI Foundry.

Modele wdrożone w usłudze Azure AI Foundry mogą być używane z indeksem LlamaIndex na dwa sposoby:

Korzystanie z interfejsu API wnioskowania modelu AI platformy Azure: Wszystkie modele wdrożone w usłudze Azure AI Foundry obsługują interfejs API wnioskowania modelu, który oferuje wspólny zestaw funkcji, których można używać w większości modeli w katalogu. Zaletą tego interfejsu API jest to, że ponieważ jest taka sama dla wszystkich modeli, zmiana z jednego na drugą jest tak prosta, jak zmiana używanego wdrożenia modelu. W kodzie nie są wymagane żadne dalsze zmiany. Podczas pracy z llamaIndex zainstaluj rozszerzenia llama-index-llms-azure-inference i llama-index-embeddings-azure-inference.
Korzystanie z interfejsu API specyficznego dla dostawcy modelu: niektóre modele, takie jak OpenAI, Cohere lub Mistral, oferują własny zestaw interfejsów API i rozszerzeń dla indeksu LlamaIndex. Rozszerzenia te mogą zawierać określone funkcje obsługiwane przez model i dlatego są odpowiednie, jeśli chcesz je wykorzystać. Podczas pracy z llama-indexprogramem zainstaluj rozszerzenie specyficzne dla modelu, którego chcesz użyć, na przykład llama-index-llms-openai lub llama-index-llms-cohere.

W tym przykładzie pracujemy z interfejsem API wnioskowania modelu.

Wymagania wstępne

Do uruchomienia tego samouczka potrzebne są następujące elementy:

Subskrypcja platformy Azure.
Projekt sztucznej inteligencji platformy Azure, zgodnie z opisem w artykule Create a project in Azure AI Foundry portal (Tworzenie projektu w portalu usługi Azure AI Foundry).
Wdrożono model obsługujący interfejs API wnioskowania modelu. W tym przykładzie Mistral-Large używamy wdrożenia, ale używamy dowolnego modelu preferencji. Do korzystania z funkcji osadzania w usłudze LlamaIndex potrzebny jest model osadzania, taki jak cohere-embed-v3-multilingual.
- Postępuj zgodnie z instrukcjami w temacie Wdrażanie modeli jako bezserwerowych wdrożeń interfejsu API.
Zainstalowano środowisko Python w wersji 3.8 lub nowszej, w tym narzędzie.
Zainstalowano właściwość LlamaIndex. Można to zrobić za pomocą:
```
pip install llama-index
```
W tym przykładzie pracujemy z interfejsem API wnioskowania modelu, dlatego instalujemy następujące pakiety:
```
pip install -U llama-index-llms-azure-inference
pip install -U llama-index-embeddings-azure-inference
```
Ważne

Korzystanie z usługi Foundry Models wymaga programu w wersji 0.2.4 dla llama-index-llms-azure-inference lub llama-index-embeddings-azure-inference.

Konfigurowanie środowiska

Aby używać usług LLM wdrożonych w portalu usługi Azure AI Foundry, potrzebny jest punkt końcowy i poświadczenia, aby nawiązać z nim połączenie. Wykonaj następujące kroki, aby uzyskać potrzebne informacje z modelu, którego chcesz użyć:

Wskazówka

Ponieważ możesz dostosować okienko po lewej stronie w portalu azure AI Foundry, możesz zobaczyć inne elementy niż pokazano w tych krokach. Jeśli nie widzisz szukanych danych, wybierz pozycję ... Więcej w dolnej części okienka po lewej stronie.

Przejdź do usługi Azure AI Foundry.
Otwórz projekt, w którym wdrożono model, jeśli nie jest jeszcze otwarty.
Przejdź do pozycji Modele i punkty końcowe i wybierz wdrożony model zgodnie z wymaganiami wstępnymi.
Skopiuj adres URL punktu końcowego i klucz.

Wskazówka

Jeśli model został wdrożony przy użyciu obsługi identyfikatora Entra firmy Microsoft, nie potrzebujesz klucza.

W tym scenariuszu ustaw adres URL punktu końcowego i klucz jako zmienne środowiskowe. (Jeśli skopiowany punkt końcowy zawiera dodatkowy tekst po /models, usuń go, aby adres URL zakończył się w /models sposób pokazany poniżej).

export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

Po skonfigurowaniu utwórz klienta w celu nawiązania połączenia z punktem końcowym.

import os
from llama_index.llms.azure_inference import AzureAICompletionsModel

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

Wskazówka

Jeśli wdrożenie modelu jest hostowane w Azure OpenAI w Foundry Models lub zasobie Azure AI Services, skonfiguruj klienta zgodnie z modele Azure OpenAI i usługa Foundry Models.

Jeśli punkt końcowy obsługuje więcej niż jeden model, na przykład w usłudze Foundry Models lub GitHub Models, musisz wskazać model_name parametr:

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-2411",
)

Alternatywnie, jeśli punkt końcowy obsługuje identyfikator Entra firmy Microsoft, możesz użyć następującego kodu, aby utworzyć klienta:

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(),
)

Uwaga / Notatka

W przypadku korzystania z identyfikatora Entra firmy Microsoft upewnij się, że punkt końcowy został wdrożony przy użyciu tej metody uwierzytelniania i że masz wymagane uprawnienia do jego wywołania.

Jeśli planujesz użycie wywołania asynchronicznego, najlepszym rozwiązaniem jest użycie wersji asynchronicznej dla poświadczeń:

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(),
)

Modele Azure OpenAI i usługa Foundry Models

Jeśli używasz usługi Azure OpenAI lub Foundry Models, upewnij się, że masz co najmniej wersję 0.2.4 integracji LlamaIndex. Użyj api_version parametru w przypadku, gdy musisz wybrać określony api_versionparametr .

W przypadku usługi Foundry Models należy przekazać model_name parametr:

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-2411",
)

W przypadku usługi Azure OpenAI w modelach rozwiązania Azure AI Foundry:

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",
)

Wskazówka

Sprawdź, która wersja interfejsu API jest używana przez wdrożenie. Użycie nieprawidłowego api_version lub nieobsługiwanego przez model powoduje ResourceNotFound wyjątek.

Parametry wnioskowania

Możesz skonfigurować sposób wnioskowania wykonywanego dla wszystkich operacji, które używają tego klienta, ustawiając dodatkowe parametry. Pomaga to uniknąć wskazywania ich przy każdym wywołaniu, które należy wykonać do modelu.

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

Parametry, które nie są obsługiwane przez API wnioskowania modelu (odwołanie), ale są dostępne w modelu bazowym, można użyć argumentu model_extras. W poniższym przykładzie parametr safe_prompt, dostępny tylko dla modeli Mistral, jest przekazywany.

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

Korzystanie z modeli LLMs

Możesz użyć klienta bezpośrednio lub skonfigurować modele używane przez kod w elemecie LlamaIndex. Aby użyć modelu bezpośrednio, użyj chat metody dla modeli instrukcji czatu:

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)

Możesz również przesyłać strumieniowo dane wyjściowe:

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

Metoda complete jest nadal dostępna dla modelu typu chat-completions. W takich przypadkach tekst wejściowy jest konwertowany na komunikat za pomocą role="user"polecenia .

Korzystanie z modeli osadzania

W taki sam sposób, jak tworzysz klienta LLM, możesz nawiązać połączenie z modelem osadzania. W poniższym przykładzie ustawiamy zmienną środowiskową tak, aby wskazywała model osadzania:

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

Następnie utwórz klienta:

from llama_index.embeddings.azure_inference import AzureAIEmbeddingsModel

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

W poniższym przykładzie pokazano prosty test, aby sprawdzić, czy działa:

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)

Konfigurowanie modeli używanych przez kod

Możesz użyć klienta modelu LLM lub osadzania indywidualnie w kodzie opracowywany za pomocą llamaIndex lub skonfigurować całą sesję przy użyciu Settings opcji. Skonfigurowanie sesji ma zaletę całego kodu przy użyciu tych samych modeli dla wszystkich operacji.

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model

Istnieją jednak scenariusze, w których chcesz użyć ogólnego modelu dla większości operacji, ale konkretnego dla danego zadania. W takich przypadkach warto ustawić używany model LLM lub model osadzający dla każdej konstrukcji LlamaIndex. W poniższym przykładzie ustawiliśmy określony model:

from llama_index.core.evaluation import RelevancyEvaluator

relevancy_evaluator = RelevancyEvaluator(llm=llm)

Ogólnie rzecz biorąc, używasz kombinacji obu strategii.

Udostępnij za pośrednictwem

Tworzenie aplikacji za pomocą biblioteki LlamaIndex i Azure AI Foundry

Wymagania wstępne

Konfigurowanie środowiska

Modele Azure OpenAI i usługa Foundry Models

Parametry wnioskowania

Korzystanie z modeli LLMs

Korzystanie z modeli osadzania

Konfigurowanie modeli używanych przez kod

Treści powiązane

Opinia

Dodatkowe zasoby