Sviluppare applicazioni con modelli e LangChain in Microsoft Foundry (versione classica)

LangChain è un ecosistema di sviluppatori che semplifica la compilazione di applicazioni di ragionamento. Include più componenti e la maggior parte di essi può essere usata in modo indipendente, in modo da poter scegliere e selezionare i componenti necessari.

È possibile usare i modelli distribuiti in Microsoft Foundry con LangChain in due modi:

Questa esercitazione illustra come usare il pacchetto langchain-azure-ai[v1] con LangChain usando Azure API di inferenza del modello di intelligenza artificiale. Alcuni modelli, ad esempio OpenAI, Cohere o Mistral, offrono le proprie API e estensioni LangChain. Queste estensioni possono includere funzionalità specifiche del modello e sono adatte se è necessario usarle. Installare l'estensione per il modello scelto, ad esempio langchain-openai o langchain-cohere.

Prerequisiti

Per eseguire questa esercitazione è necessario:

• Un account Azure con una sottoscrizione attiva. Se non hai uno, crea un account Azure gratuito, che include un abbonamento di prova gratuito.

• Ruolo obbligatorio:
  • Proprietario o Collaboratore nella risorsa Foundry o nell'hub di intelligenza artificiale per distribuire i modelli
  • Utente di Azure AI per usare il modello in un progetto Foundry
  • Azure AI Developer per utilizzare il modello in un progetto basato su hub

• Distribuzione di modelli che supporta l'API di inferenza del modello. Questo articolo usa Mistral-Large-3.

• Python 3.9 o versione successiva installata, incluso pip.

• LangChain installato. È possibile installarlo usando il comando seguente:

  pip install langchain
  

• Installare l'integrazione di Foundry:

  pip install -U langchain-azure-ai[v1]
  

Configurare l'ambiente

Per usare i moduli di llms distribuiti nel portale di Microsoft Foundry, sono necessarie l'endpoint e le credenziali per la connessione. Per ottenere le informazioni necessarie dal modello da usare, seguire questa procedura:

1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

   

2. Aprire il progetto in cui viene distribuito il modello, se non è già aperto.

3. Copiare l'URL dell'endpoint e la chiave.

In questo scenario impostare l'URL dell'endpoint e la chiave come variabili di ambiente. Se l'endpoint copiato include testo aggiuntivo dopo /models, rimuoverlo in modo che l'URL termini a /models come mostrato di seguito.

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

Creare un client per connettersi al modello di chat usando la AzureAIChatCompletionsModel classe .

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

Qual è la funzione di questo frammento: crea un'istanza di un client AzureAIChatCompletionsModel configurato per connettersi al modello distribuito usando una chiave API per l'autenticazione. Questo client funge da interfaccia per l'API di inferenza del modello.

Riferimenti:

• integrazione dell'intelligenza artificiale di LangChain Azure
• Panoramica dell'API di inferenza del modello

Se l'endpoint supporta Microsoft Entra ID, usare il codice seguente per creare il client:

import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
)

Se si prevede di usare chiamate asincrone, usare la versione asincrona delle credenziali:

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="Mistral-Large-3",
)

Se l'endpoint serve un singolo modello (ad esempio, distribuzioni di API serverless), non includere il model parametro :

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_AI_CREDENTIAL"],
)

Verificare la configurazione

Testare la connessione client con una semplice chiamata:

response = model.invoke("Say hello")
print(response.content)

Operazioni seguenti: Chiama il modello con un semplice prompt per verificare l'autenticazione e la connettività. Output previsto: messaggio di saluto del modello (ad esempio, "Hello! Come posso aiutarti oggi?").

Riferimenti:

• Interfaccia Runnable di LangChain

Usare i modelli di completamento della chat

Usare direttamente il modello. ChatModels sono istanze dell'interfaccia LangChain Runnable , che fornisce un modo standard per interagire con loro. Per chiamare il modello, passare un elenco di messaggi al invoke metodo .

from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="Translate the following from English into Italian"),
    HumanMessage(content="hi!"),
]

model.invoke(messages)

Cosa fa questo frammento di codice: Viene illustrato come passare un elenco di HumanMessage oggetti e SystemMessage al metodo del invoke() modello per generare una risposta.

Riferimenti:

• Messaggi LangChain
• Interfaccia Runnable di LangChain

Comporre le operazioni secondo necessità in sequenze. Usare un modello di prompt per tradurre le frasi:

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

system_template = "Translate the following into {language}:"
prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

Questa catena riceve i input language e text. Ora, crea un parser di output:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Cosa fa questo frammento di codice: Crea un oggetto StrOutputParser che converte l'output del modello in un formato stringa, rimuovendo eventuali metadati aggiuntivi.

Riferimenti:

• Parser di output LangChain

Combinare il template, il modello matematico e il parser di output usando l'operatore pipe (|):

chain = prompt_template | model | parser

Fornire i valori language e text usando il metodo invoke per richiamare la catena.

chain.invoke({"language": "italian", "text": "hi"})

Concatenare più LLM insieme

Poiché i modelli in Foundry espongono un'API di inferenza modello comune, è possibile concatenare più operazioni LLM e scegliere il modello più adatto a ogni passaggio.

Nell'esempio seguente vengono creati due client modello: un producer e un verificatore. Per chiarire la distinzione, utilizzare un endpoint multimodello, come ad esempio l'API di inferenza del modello, e passare il parametro model a un modello di grandi dimensioni per la generazione e a uno di piccole dimensioni per la verifica. La produzione di contenuto richiede in genere un modello di dimensioni maggiori, mentre la verifica può usare un modello più piccolo.

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

producer = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

verifier = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="mistral-small",
)

Cosa fa questo frammento: Crea un'istanza di due client distinti AzureAIChatCompletionsModel: uno che usa Mistral-Large-3 per la generazione di contenuti e un altro che usa Mistral-Small per la verifica, dimostrando come scegliere modelli diversi per attività diverse.

Riferimenti:

• integrazione dell'intelligenza artificiale di LangChain Azure

L'esempio seguente genera una poesia scritta da un poeta urbano:

from langchain_core.prompts import PromptTemplate

producer_template = PromptTemplate(
    template="You are an urban poet, your job is to come up \
             verses based on a given topic.\n\
             Here is the topic you have been asked to generate a verse on:\n\
             {topic}",
    input_variables=["topic"],
)

verifier_template = PromptTemplate(
    template="You are a verifier of poems, you are tasked\
              to inspect the verses of poem. If they consist of violence and abusive language\
              report it. Your response should be only one word either True or False.\n \
              Here is the lyrics submitted to you:\n\
              {input}",
    input_variables=["input"],
)

Cosa fa questo frammento di codice: Crea un modello di richiesta e lo concatena con il producer client modello per generare contenuto creativo (in questo caso una poesia).

Concatenare i pezzi:

chain = producer_template | producer | parser | verifier_template | verifier | parser

Cosa fa questo frammento di codice: Concatena il poema generato tramite il verifier modello per convalidare o esaminare il contenuto generato, dimostrando un flusso di lavoro producer-verifier.

La catena precedente restituisce solo l'output del verifier passaggio. Per accedere al risultato intermedio generato da producer, usare un RunnablePassthrough oggetto per restituire tale passaggio intermedio.

from langchain_core.runnables import RunnablePassthrough, RunnableParallel

generate_poem = producer_template | producer | parser
verify_poem = verifier_template | verifier | parser

chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verification=RunnablePassthrough() | verify_poem)

Richiama la catena utilizzando il metodo invoke

chain.invoke({"topic": "living in a foreign country"})

Qual è la funzione di questo frammento: chiama la catena producer-verifier completa con un input di argomento, restituendo sia il contenuto generato sia il risultato della verifica. Output previsto: un oggetto JSON contenente le chiavi poem e verification con la poesia generata e la risposta di verifica.

Riferimenti:

• Eseguibili LangChain

Usare l'incorporamento dei modelli

Creare un client di incorporamenti in modo analogo. Impostare le variabili di ambiente in modo che puntino a un modello di incorporamento:

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

Creare il client:

import os
from langchain_azure_ai.embeddings import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="text-embedding-3-large",
)

Cosa fa questo frammento di codice: Esegue un'istanza di un client di incorporamenti usando AzureAIEmbeddingsModel per convertire il testo in incorporamenti vettoriali, che possono essere usati per ricerche semantiche e confronti di somiglianza.

Riferimenti:

• Incorporazioni LangChain

Usare un archivio vettoriale in memoria:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Cosa fa questo frammento di codice: Crea un archivio vettoriale in memoria (InMemoryVectorStore) che archivia gli incorporamenti per operazioni di ricerca di somiglianza veloci.

Riferimenti:

• LangChain Vector Stores

Aggiungere documenti:

from langchain_core.documents import Document

document_1 = Document(id="1", page_content="foo", metadata={"baz": "bar"})
document_2 = Document(id="2", page_content="thud", metadata={"bar": "baz"})

documents = [document_1, document_2]
vector_store.add_documents(documents=documents)

Cosa fa questo frammento di codice: Converte i documenti in incorporamenti usando il client di incorporamenti e li aggiunge all'archivio vettoriale per il recupero successivo.

Riferimenti:

• LangChain Vector Stores

Ricerca per somiglianza:

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

Cosa fa questo frammento di codice: Esegue una ricerca semantica nell'archivio vettoriale, restituendo documenti più simili alla query in base alla somiglianza di incorporamento. Output previsto: elenco dei documenti pertinenti classificati in base al punteggio di somiglianza.

Usare i modelli OpenAI di Azure

Quando si usano Azure modelli OpenAI con il pacchetto langchain-azure-ai, usare il formato endpoint seguente:

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

llm = AzureAIChatCompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/v1",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="gpt-4o"
)

Operazione dello snippet: creazione di un'istanza di un client configurato in modo specifico per i modelli Azure OpenAI utilizzando il formato dell'endpoint di Azure OpenAI. Il parametro endpoint punta alla risorsa OpenAI Azure e l'credential usa la chiave API archiviata nella variabile di ambiente.

Riferimenti:

• integrazione dell'intelligenza artificiale di LangChain Azure

Debug e risoluzione dei problemi

Se è necessario eseguire il debug dell'applicazione e comprendere le richieste inviate ai modelli in Foundry, usare le funzionalità di debug dell'integrazione:

Configurare prima di tutto la registrazione al livello desiderato:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

Che questo frammento di codice fa: configura la registrazione Python a livello di DEBUG per acquisire informazioni dettagliate sulle richieste HTTP e le risposte tra LangChain e l'API di inferenza del modello.

Riferimenti:

• Modulo di registrazione Python

Per visualizzare i payload delle richieste, passare logging_enable=True in client_kwargs quando si crea un'istanza del client:

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
    client_kwargs={"logging_enable": True},
)

Cosa fa questo frammento di codice: Crea un client con registrazione abilitata per acquisire e visualizzare payload dettagliati di richiesta/risposta, utili per il debug delle interazioni api.

Usare il client nel codice come di consueto.

Traccia

Usare la traccia in Fonderia creando un'utilità di traccia. I log vengono archiviati in Azure Application Insights e possono essere sottoposti a query in qualsiasi momento usando Azure Monitor o il portale foundry. Ogni hub di intelligenza artificiale ha un'istanza di Azure Application Insights associata.

Ottenere la stringa di connessione della strumentazione

È possibile configurare l'applicazione per inviare dati di telemetria a Azure Application Insights usando uno dei metodi seguenti:

1. Usare la stringa di connessione per Azure Application Insights direttamente:

   1. Accedere al portale di Foundry e selezionare Tracciamento.

   2. Selezionare Gestisci origine dati. In questa schermata è possibile visualizzare l'istanza associata al progetto.

   3. Copiare il valore in Stringa di connessione e impostarlo sulla variabile seguente:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Usa il Microsoft Foundry SDK e l'endpoint del Foundry Project:

   1. Assicurarsi di avere installato il pacchetto azure-ai-projects nell'ambiente in uso.

   2. Passare al portale di Foundry.

   3. Copiare l'URL dell'endpoint del progetto Foundry e impostarlo nel codice seguente:

      from azure.ai.projects import AIProjectClient
      from azure.identity import DefaultAzureCredential
      
      project_client = AIProjectClient(
          credential=DefaultAzureCredential(),
          endpoint="<your-foundry-project-endpoint-url>",
      )
      
      application_insights_connection_string = project_client.telemetry.get_application_insights_connection_string()
      

Altre informazioni su come visualizzare e gestire le tracce.

Passaggi successivi

• Sviluppare applicazioni con LlamaIndex
• Visualizzare e gestire tracce in Foundry
• Usare i modelli Foundry
• Riferimento: API di inferenza del modello