Usare LangChain con i modelli in Microsoft Foundry

Usare langchain-azure-ai per compilare app LangChain che chiamano modelli distribuiti in Microsoft Foundry. I modelli con API compatibili con OpenAI possono essere usati direttamente. In questo articolo si creano client di chat e incorporamenti, si eseguono catene di richieste e si combina la generazione con i flussi di lavoro di verifica.

Prerequisiti

• Sottoscrizione Azure. Crearne uno gratuitamente.
• Progetto Foundry.
• Ruolo di utente di intelligenza artificiale Azure nel progetto Foundry.
• Modello di chat distribuito che supporta LE API compatibili con OpenAI, ad esempio gpt-4.1 o Mistral-Large-3.
• Modello di incorporamento distribuito, ad esempio text-embedding-3-large.
• Python 3.9 o versione successiva.

Installare i pacchetti necessari:

pip install -U langchain langchain-azure-ai azure-identity

Configurare l'ambiente

Impostare uno dei modelli di connessione seguenti:

• Punto finale del progetto utilizzando Microsoft Entra ID (scelta consigliata).
• Endpoint diretto con una chiave API.

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"

Cosa fa questo frammento di codice: Definisce le variabili di ambiente usate dalle langchain-azure-ai classi di modello per l'accesso diretto o basato su progetto.

Usare i modelli di chat

È possibile creare facilmente un'istanza di un modello usando init_chat_model:

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-4.1")

Tutti i modelli Foundry che supportano LE API compatibili con OpenAI possono essere usati con il client, ma devono essere distribuiti prima nella risorsa Foundry. L'uso di project_endpoint (variabile di ambiente AZURE_AI_PROJECT_ENDPOINT) richiede Microsoft Entra ID per l'autenticazione e il ruolo Azure AI User.

Cosa fa questo frammento di codice: Crea un client modello di chat usando il init_chat_model metodo di praticità. Il client esegue il routing al modello specificato tramite l'endpoint del progetto Foundry o l'endpoint diretto configurato nell'ambiente.

Riferimenti:

• AzureAIOpenAIApiChatModel

Verificare la configurazione

Eseguire una chiamata a un modello semplice:

response = model.invoke("Say hello")
response.pretty_print()

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Cosa fa questo frammento di codice: Invia un prompt di base per verificare l'endpoint, l'autenticazione e il routing del modello.

Riferimenti:

• Interfaccia eseguibile di LangChain

Modelli configurabili

È anche possibile creare un modello configurabile dal runtime specificando configurable_fields. Quando si omette il model parametro, diventa un campo configurabile per impostazione predefinita.

from langchain.chat_models import init_chat_model
from azure.identity import DefaultAzureCredential

configurable_model = init_chat_model(
    model_provider="azure_ai", 
    temperature=0,
	credential=DefaultAzureCredential()
)


configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-nano
).pretty_print()

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "Mistral-Large-3"}}, # Run with Mistral Large
).pretty_print()

================================== Ai Message ==================================

Hi! I'm ChatGPT, an AI assistant built by OpenAI. You can call me ChatGPT or just Assistant. How can I help you today?
================================== Ai Message ==================================

I don't have a name, but you can call me **Assistant** or anything you like! 😊 What can I help you with today?

Cosa fa questo frammento di codice: Crea un'istanza del modello configurabile che consente di cambiare facilmente i modelli in fase di chiamata. Poiché il model parametro non è presente in init_chat_model, per impostazione predefinita è un campo configurabile e può essere passato con invoke(). È possibile aggiungere altri campi da configurare configurando configurable_fields.

Configurare direttamente i client

È anche possibile creare un client del modello di chat usando AzureAIOpenAIApiChatModel la classe .

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="Mistral-Large-3",
)

Per impostazione predefinita, AzureAIOpenAIApiChatModel usa l'API Risposte OpenAI. È possibile modificare questo comportamento passando use_responses_api=False:

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
    use_responses_api=False
)

Eseguire chiamate asincrone

Usare le credenziali asincrone se l'app chiama i modelli con ainvoke. Quando si usa Microsoft Entra ID per l'autenticazione, usare l'implementazione asincrona corrispondente per le credenziali:

import os

from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredentialAsync(),
	model="gpt-4.1",
)


async def main():
	response = await model.ainvoke("Say hello asynchronously")
	response.pretty_print()


import asyncio
asyncio.run(main())

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Cosa fa questo frammento di codice: Crea un client asincrono ed esegue una richiesta non bloccante con ainvoke.

Riferimenti:

• Credenziali asincrone in Azure Identity
• Interfaccia eseguibile di LangChain

Ragionamento

Molti modelli possono eseguire un ragionamento in più passaggi per arrivare a una conclusione. Ciò comporta la suddivisione di problemi complessi in passaggi più piccoli e gestibili.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:DeepSeek-R1-0528")

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text, end="")

print("\n")

Parrots have colorful feathers primarily due to a combination of evolutionary ...

Riferimenti:

• Streaming LangChain

Strumenti lato server

I modelli OpenAI distribuiti in Foundry supportano cicli di chiamata a strumenti sul lato server: i modelli possono interagire con la ricerca Web, gli interpreti di codice e altri strumenti e quindi analizzare i risultati in un unico turno di conversazione. Se un modello richiama un lato server degli strumenti, il contenuto del messaggio di risposta includerà il contenuto che rappresenta la chiamata e il risultato dello strumento.

Questi sono strumenti forniti da OpenAI che estendono le funzionalità del modello. Per visualizzare l'elenco completo degli strumenti supportati, vedere Strumenti predefiniti.

L'esempio seguente illustra come usare la ricerca Web:

from langchain.chat_models import init_chat_model
from langchain_azure_ai.tools.builtin import WebSearchTool
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1", credential=DefaultAzureCredential())
model_with_web_search = model.bind_tools([WebSearchTool()])

result = model_with_web_search.invoke("What is the current price of gold? Give me the answer in one sentence.")
result.content[-1]["text"]

As of today, March 24, 2026, the spot price of gold is approximately $4,397.80 per ounce. ([tradingeconomics.com](https://tradingeconomics.com/commodity/gold))

Alcuni strumenti potrebbero richiedere la configurazione di altre risorse nel progetto. Usare azure-ai-projects per configurare tali risorse e quindi farvi riferimento da LangChain/LangGraph.

L'esempio seguente illustra come configurare un archivio file prima di usarlo in uno strumento:

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

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
vector_store_id = vector_store.id

with open("product_info.md", "rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

Che questo frammento di codice fa: Configura un archivio vettoriale con un file in Microsoft Foundry in modo che un modello possa eseguire una ricerca successiva sul contenuto del file (usato con il FileSearchTool nel blocco di codice successivo).

from langchain_azure_ai.tools.builtin import FileSearchTool

model_with_tools = model.bind_tools([FileSearchTool(vector_store_ids=[vector_store.id])])

results = model_with_tools.invoke("Tell me about Contoso products")
print("Answer:", results.content[-1]["text"])
print("Annotations:", results.content[-1]["annotations"])

Answer: Contoso offers the following products:

1. **The widget**
   - Description: A high-quality widget that is perfect for all your widget needs.
   - Price: $19.99

2. **The gadget**
   - Description: An advanced gadget that offers exceptional performance and reliability.
   - Price: $49.99

These products are part of Contoso's main offerings as detailed in their product information documentation.
Annotations: [{'file_id': 'assistant-MvU5SEqUcUBumoLUV5BXxn', 'filename': 'product_info.md', 'type': 'file_citation', 'file_index': 395}]

Usare i modelli Foundry negli agenti

Usare create_agent con i modelli collegati a Foundry per creare loop di agenti in stile ReAct:

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

Gli strumenti lato server possono essere utilizzati, ma richiedono di chiamare bind_tools.

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain_azure_ai.tools.builtin import ImageGenerationTool

model = init_chat_model("azure_ai:gpt-5.2")
tools = [ImageGenerationTool(model="gpt-image-1.5", size="1024x1024")]
model_with_tools = model.bind_tools(tools)

agent = create_agent(
    model=model_with_tools,
    tools=tools,
    system_prompt="You're an informational agent. Answer questions with graphics.", 
)

Usare i modelli di incorporamento

È possibile creare facilmente un'istanza di un modello usando init_embeddings:

from langchain.embeddings import init_embeddings

embed_model = init_embeddings("azure_ai:text-embedding-3-small")

Cosa fa questo frammento di codice: Crea un client del modello di embedding usando il init_embeddings metodo di convenienza.

Tutti i modelli Foundry che supportano LE API compatibili con OpenAI possono essere usati con il client, ma devono essere distribuiti prima nella risorsa Foundry. L'uso di project_endpoint (variabile di ambiente AZURE_AI_PROJECT_ENDPOINT) richiede Microsoft Entra ID per l'autenticazione e il ruolo Azure AI User.

In alternativa, creare il client di incorporamenti con AzureAIOpenAIApiEmbeddingsModel.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="text-embedding-3-large",
)

Per l'autenticazione diretta dell'endpoint e della chiave API:

import os

from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	endpoint=os.environ["OPENAI_BASE_URL"],
	credential=os.environ["OPENAI_API_KEY"],
	model="text-embedding-3-large",
)

Cosa fa questo frammento di codice: Configura la generazione di incorporamenti per i flussi di lavoro di ricerca, recupero e classificazione vettoriali.

Riferimenti:

• AzureAIOpenAIApiEmbeddingsModel

Esempio: Eseguire una ricerca di somiglianza con un archivio vettoriale

Usare un archivio vettoriale in memoria per la sperimentazione locale.

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

documents = [
	Document(id="1", page_content="foo", metadata={"baz": "bar"}),
	Document(id="2", page_content="thud", metadata={"bar": "baz"}),
]

vector_store.add_documents(documents=documents)

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

* thud [{'bar': 'baz'}]

Cosa fa questo frammento di codice: Aggiunge documenti di esempio a un archivio vettoriale e restituisce il documento più simile per una query.

Riferimenti:

• Archivi vettoriali LangChain

Eseguire il debug delle richieste con la registrazione

Abilitare langchain_azure_ai la registrazione di debug per controllare il flusso di richiesta.

import logging
import sys

logger = logging.getLogger("langchain_azure_ai")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter(
	"%(asctime)s:%(levelname)s:%(name)s:%(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)

Che questo frammento di codice fa: Configura la registrazione Python per generare log SDK dettagliati che consentono di risolvere i problemi relativi all'endpoint o al payload.

Riferimenti:

• Python logging

Informazioni di riferimento sulle variabili di ambiente

È possibile configurare le variabili di ambiente seguenti. Questi valori possono essere configurati anche durante la costruzione degli oggetti:

Passaggio successivo

Contenuto correlato

• Panoramica dei modelli di fonderia
• Panoramica di Microsoft Foundry SDK
• Utilizzare LangChain con memoria nel contesto di Foundry
• Utilizzo di LangChain con il servizio agente di Foundry