Merge pull request #5696 from sdgilley/sdg-freshness

freshness update - articles/ai-foundry/how-to/develop/langchain.md

Author: v-dirichards

articles/ai-foundry/how-to/develop/langchain.md

@@ -7,7 +7,7 @@ ms.service: azure-ai-foundry
 ms.custom:
   - ignite-2024
 ms.topic: how-to
-ms.date: 03/11/2025
+ms.date: 06/24/2025
 ms.reviewer: fasantia
 ms.author: sgilley
 author: sdgilley
@@ -30,12 +30,13 @@ In this tutorial, you learn how to use the packages `langchain-azure-ai` to buil
 To run this tutorial, you need:
 
 * An [Azure subscription](https://azure.microsoft.com).
-* A model deployment supporting the [Model Inference API](https://aka.ms/azureai/modelinference) deployed. In this example, we use a `Mistral-Large-2407` deployment in the [Foundry Models](../../../ai-foundry/model-inference/overview.md).
+
+* A model deployment supporting the [Model Inference API](https://aka.ms/azureai/modelinference) deployed. In this example, we use a `Mistral-medium-2505` deployment in the [Foundry Models](../../../ai-foundry/model-inference/overview.md).
 * Python 3.9 or later installed, including pip.
 * LangChain installed. You can do it with:
 
     ```bash
-    pip install langchain-core
+    pip install langchain
     ```
 
 * In this example, we're working with the Model Inference API, hence we install the following packages:
@@ -63,7 +64,7 @@ To use LLMs deployed in Azure AI Foundry portal, you need the endpoint and crede
     > [!TIP]
     > If your model was deployed with Microsoft Entra ID support, you don't need a key.
 
-In this scenario, we placed both the endpoint URL and key in the following environment variables:
+In this scenario, set the endpoint URL and key as environment variables. (If the endpoint you copied includes additional text after `/models`, remove it so the URL ends at `/models` as shown below.)
 
 ```bash
 export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
@@ -75,21 +76,13 @@ Once configured, create a client to connect with the chat model by using the `in
 ```python
 from langchain.chat_models import init_chat_model
 
-llm = init_chat_model(model="mistral-large-2407", model_provider="azure_ai")
+llm = init_chat_model(model="mistral-medium-2505", model_provider="azure_ai")
 ```
 
 You can also use the class `AzureAIChatCompletionsModel` directly.
 
-```python
-import os
-from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=create_client)]
 
-model = AzureAIChatCompletionsModel(
-    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
-    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
-    model="mistral-large-2407",
-)
-```
 
 > [!CAUTION]
 > **Breaking change:** Parameter `model_name` was renamed `model` in version `0.1.3`.
@@ -104,7 +97,7 @@ from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel
 model = AzureAIChatCompletionsModel(
     endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
     credential=DefaultAzureCredential(),
-    model="mistral-large-2407",
+    model="mistral-medium-2505",
 )
 ```
 
@@ -122,7 +115,7 @@ from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel
 model = AzureAIChatCompletionsModel(
     endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
     credential=DefaultAzureCredentialAsync(),
-    model="mistral-large-2407",
+    model="mistral-medium-2505",
 )
 ```
 
@@ -142,21 +135,13 @@ model = AzureAIChatCompletionsModel(
 
 Let's first use the model directly. `ChatModels` are instances of LangChain `Runnable`, which means they expose a standard interface for interacting with them. To call the model, we can pass in a list of messages to the `invoke` method.
 
-```python
-from langchain_core.messages import HumanMessage, SystemMessage
-
-messages = [
-    SystemMessage(content="Translate the following from English into Italian"),
-    HumanMessage(content="hi!"),
-]
-
-model.invoke(messages)
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=human_message)] 
 
 You can also compose operations as needed in **chains**. Let's now use a prompt template to translate sentences:
 
 ```python
 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(
@@ -166,10 +151,7 @@ prompt_template = ChatPromptTemplate.from_messages(
 
 As you can see from the prompt template, this chain has a `language` and `text` input. Now, let's create an output parser:
 
-```python
-from langchain_core.prompts import ChatPromptTemplate
-parser = StrOutputParser()
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=create_output_parser)]
 
 We can now combine the template, model, and the output parser from above using the pipe (`|`) operator:
 
@@ -183,65 +165,27 @@ To invoke the chain, identify the inputs required and provide values using the `
 chain.invoke({"language": "italian", "text": "hi"})
 ```
 
-```output
-'ciao'
-```
-
 ### Chaining multiple LLMs together
 
 Models deployed to Azure AI Foundry support the Model Inference API, which is standard across all the models. Chain multiple LLM operations based on the capabilities of each model so you can optimize for the right model based on capabilities. 
 
-In the following example, we create two model clients. One is a producer and another one is a verifier. To make the distinction clear, we're using a multi-model endpoint like the [Model Inference API](../../model-inference/overview.md) and hence we're passing the parameter `model` to use a `Mistral-Large` and a `Mistral-Small` model, quoting the fact that **producing content is more complex than verifying it**.
-
-```python
-from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel
+In the following example, we create two model clients. One is a producer and another one is a verifier. To make the distinction clear, we're using a multi-model endpoint like the [Foundry Models API](../../model-inference/overview.md) and hence we're passing the parameter `model` to use a `Mistral-Medium` and a `Mistral-Small` model, quoting the fact that **producing content is more complex than verifying it**.
 
-producer = AzureAIChatCompletionsModel(
-    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
-    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
-    model="mistral-large-2407",
-)
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=create_producer_verifier)]
 
-verifier = AzureAIChatCompletionsModel(
-    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
-    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
-    model="mistral-small",
-)
-```
 
 > [!TIP]
 > Explore the model card of each of the models to understand the best use cases for each model.
 
 The following example generates a poem written by an urban poet:
 
-```python
-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"],
-)
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=generate_poem)]
 
 Now let's chain the pieces:
 
-```python
-chain = producer_template | producer | parser | verifier_template | verifier | parser
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=create_chain)]
 
-The previous chain returns the output of the step `verifier` only. Since we want to access the intermediate result generated by the `producer`, in LangChain you need to use a `RunnablePassthrough` object to also output that intermediate step. The following code shows how to do it:
+The previous chain returns the output of the step `verifier` only. Since we want to access the intermediate result generated by the `producer`, in LangChain you need to use a `RunnablePassthrough` object to also output that intermediate step. 
 
 ```python
 from langchain_core.runnables import RunnablePassthrough, RunnableParallel
@@ -254,16 +198,8 @@ chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verificatio
 
 To invoke the chain, identify the inputs required and provide values using the `invoke` method:
 
-```python
-chain.invoke({"topic": "living in a foreign country"})
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=invoke_chain)]
 
-```output
-{
-  "peom": "...",
-  "verification: "false"
-}
-```
 
 ## Use embeddings models
 
@@ -276,43 +212,21 @@ export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"
 
 Then create the client:
 
-```python
-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",
-)
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-embeddings.ipynb?name=create_embed_model_client)]
 
 The following example shows a simple example using a vector store in memory:
 
-```python
-from langchain_core.vectorstores import InMemoryVectorStore
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-embeddings.ipynb?name=create_vector_store)]
 
-vector_store = InMemoryVectorStore(embed_model)
-```
 
 Let's add some documents:
 
-```python
-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"})
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-embeddings.ipynb?name=add_documents)]
 
-documents = [document_1, document_2]
-vector_store.add_documents(documents=documents)
-```
 
 Let's search by similarity:
 
-```python
-results = vector_store.similarity_search(query="thud",k=1)
-for doc in results:
-    print(f"* {doc.page_content} [{doc.metadata}]")
-```
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-embeddings.ipynb?name=search_similarity)]
 
 ## Using Azure OpenAI models
 
@@ -334,41 +248,13 @@ If you need to debug your application and understand the requests sent to the mo
 
 First, configure logging to the level you are interested in:
 
-```python
-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)
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=configure_logging)]
 
-# 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)
-```
 
 To see the payloads of the requests, when instantiating the client, pass the argument `logging_enable`=`True` to the `client_kwargs`:
 
-```python
-import os
-from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel
+[!notebook-python[](~/azureai-samples-main/scenarios/langchain/getting-started-with-langchain-chat-models.ipynb?name=create_client_with_logging)]
 
-model = AzureAIChatCompletionsModel(
-    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
-    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
-    model="mistral-large-2407",
-    client_kwargs={"logging_enable": True},
-)
-```
 
 Use the client as usual in your code.
 
@@ -396,7 +282,7 @@ You can configure your application to send telemetry to Azure Application Insigh
         application_insights_connection_string = "instrumentation...."
         ```
 
-2. Using the Azure AI Foundry SDK and the project connection string.
+2. Using the Azure AI Foundry SDK and the project connection string (**[!INCLUDE [hub-project-name](../../includes/hub-project-name.md)]s only**).
 
     1. Ensure you have the package `azure-ai-projects` installed in your environment.