Merge pull request #5030 from MicrosoftDocs/main

5/19/2025 AM Publish

Author: Taojunshen

articles/ai-foundry/how-to/create-projects.md

@@ -176,7 +176,7 @@ In addition, many resources are only accessible by users in your project workspa
 
 ## Related content
 
-- [Deploy an enterprise chat web app](../tutorials/deploy-chat-web-app.md)
+- [Quickstart: Get started with Azure AI Foundry](../quickstarts/get-started-code.md?pivots=hub-project)
 
 - [Learn more about Azure AI Foundry](../what-is-azure-ai-foundry.md)
 

articles/ai-foundry/how-to/develop/trace-application.md

@@ -57,38 +57,37 @@ To view traces in Azure AI Foundry, you need to connect an Application Insights
 To trace the content of chat messages, set the `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable to true (case insensitive). Keep in mind this might contain personal data. To learn more, see [Azure Core Tracing OpenTelemetry client library for Python](/python/api/overview/azure/core-tracing-opentelemetry-readme).
 
 ```python
-from opentelemetry import trace
-from azure.monitor.opentelemetry import configure_azure_monitor
-from azure.ai.projects import AIProjectClient
-from azure.identity import DefaultAzureCredential
 import os
-
 os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default
+```
+Let's begin instrumenting our agent with OpenTelemetry tracing, by starting off with authenticating and connecting to your Azure AI Project using the `AIProjectClient`.
 
+```python
+from azure.ai.projects import AIProjectClient
+from azure.identity import DefaultAzureCredential
 project_client = AIProjectClient.from_connection_string(
     credential=DefaultAzureCredential(),
-    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
+    endpoint=os.environ["PROJECT_ENDPOINT"],
 )
 ```
 
-### Log to Azure Monitor Application Insights
-
-Retrieve the connection string from the Application Insights resource connected to your project and set up the OTLP exporters to send telemetry into Azure Monitor.
+Next, retrieve the connection string from the Application Insights resource connected to your project and set up the OTLP exporters to send telemetry into Azure Monitor.
 
 ```python
+from azure.monitor.opentelemetry import configure_azure_monitor
 connection_string = project_client.telemetry.get_connection_string()
 
 if not connection_string:
-    print("Application Insights is not enabled. Enable by going to Observability > Traces in your AI Foundry project.")
+    print("Application Insights is not enabled. Enable by going to Tracing in your Azure AI Foundry project.")
     exit()
 
-configure_azure_monitor(connection_string=connection_string)
+configure_azure_monitor(connection_string=connection_string) #enable telemetry collection
 ```
 
-Start collecting telemetry and send to your project's connected Application Insights resource.
+Now, trace your code where you create and execute your agent and user message in your Azure AI Project, so you can see detailed steps for troubleshooting or monitoring.
 
 ```python
-# Start tracing
+from opentelemetry import trace
 tracer = trace.get_tracer(__name__)
 
 with tracer.start_as_current_span("example-tracing"):
@@ -104,23 +103,59 @@ with tracer.start_as_current_span("example-tracing"):
     run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)
 ```
 
-### Log to a local OTLP endpoint
+After running your agent, you can go begin to [view traces in Azure AI Foundry Portal](#view-traces-in-azure-ai-foundry-portal).
+
+### Log traces locally
 
-To connect to Aspire Dashboard or another OpenTelemetry compatible backend, install the OpenTelemetry Protocol (OTLP) exporter. This enables you to print traces to the console or use a local viewer such as Aspire Dashboard.
+To connect to [Aspire Dashboard](https://aspiredashboard.com/#start) or another OpenTelemetry compatible backend, install the OpenTelemetry Protocol (OTLP) exporter. This enables you to print traces to the console or use a local viewer such as Aspire Dashboard.
 
 ```bash
-pip install opentelemetry-exporter-otlp
+pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk
 ```
+Next, you want to configure tracing for your application.
 
 ```python
-# Enable console tracing
-project_client.telemetry.enable(destination=sys.stdout)
+from azure.core.settings import settings
+settings.tracing_implementation = "opentelemetry"
 
-# for local OTLP endpoint, change the destination to
-# project_client.telemetry.enable(destination="http://localhost:4317")
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
+
+# Setup tracing to console
+span_exporter = ConsoleSpanExporter()
+tracer_provider = TracerProvider()
+tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
+trace.set_tracer_provider(tracer_provider)
 ```
+Use `enable_telemetry` to begin collecting telemetry. 
 
-### Trace custom functions
+```python
+from azure.ai.projects import enable_telemetry
+enable_telemetry(destination=sys.stdout)
+
+# Logging to an OTLP endpoint, change the destination to
+# enable_telemetry(destination="http://localhost:4317")
+```
+```python
+# Start tracing
+from opentelemetry import trace
+tracer = trace.get_tracer(__name__)
+
+with tracer.start_as_current_span("example-tracing"):
+    agent = project_client.agents.create_agent(
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        name="my-assistant",
+        instructions="You are a helpful assistant"
+    )
+    thread = project_client.agents.create_thread()
+    message = project_client.agents.create_message(
+        thread_id=thread.id, role="user", content="Tell me a joke"
+    )
+    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)
+```
+
+## Trace custom functions
 
 To trace your custom functions, use the OpenTelemetry SDK to instrument your code.
 
@@ -149,34 +184,26 @@ custom_function()
 
 For detailed instructions and advanced usage, refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/).
 
-### Attach user feedback to traces
+## Attach user feedback to traces
 
-To attach user feedback to traces and visualize it in the Azure AI Foundry portal, you can instrument your application to enable tracing and log user feedback using OpenTelemetry's semantic conventions. By correlating feedback traces with their respective chat request traces using the response ID, you can view and manage these traces in Azure AI Foundry portal. OpenTelemetry's specification allows for standardized and enriched trace data, which can be analyzed in Azure AI Foundry portal for performance optimization and user experience insights. This approach helps you use the full power of OpenTelemetry for enhanced observability in your applications.
+To attach user feedback to traces and visualize it in the Azure AI Foundry portal, you can instrument your application to enable tracing and log user feedback using OpenTelemetry's semantic conventions. 
 
-To log user feedback, follow this format:
 
-The user feedback evaluation event can be captured if and only if the user provided a reaction to the GenAI model response. It SHOULD, when possible, be parented to the GenAI span describing such response.
 
-<!-- prettier-ignore-start -->
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
-The event name MUST be `gen_ai.evaluation.user_feedback`.
+By correlating feedback traces with their respective chat request traces using the response ID or thread ID, you can view and manage these traces in Azure AI Foundry portal. OpenTelemetry's specification allows for standardized and enriched trace data, which can be analyzed in Azure AI Foundry portal for performance optimization and user experience insights. This approach helps you use the full power of OpenTelemetry for enhanced observability in your applications.
+
+To log user feedback, follow this format:
 
-| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-|---|---|---|---|---|---|
-|`gen_ai.response.id`| string | The unique identifier for the completion. | `chatcmpl-123` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `gen_ai.evaluation.score`| double | Quantified score calculated based on the user reaction in [-1.0, 1.0] range with 0 representing a neutral reaction. | `0.42` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+The user feedback evaluation event can be captured if and only if the user provided a reaction to the GenAI model response. It SHOULD, when possible, be parented to the GenAI span describing such response.
 
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
 
 The user feedback event body has the following structure:
 
 | Body Field | Type | Description | Examples | Requirement Level |
 |---|---|---|---|---|
 | `comment` | string | Additional details about the user feedback | `"I did not like it"` | `Opt-in` |
 
-### Using service name in trace data
+## Using service name in trace data
 
 To identify your service via a unique ID in Application Insights, you can use the service name OpenTelemetry property in your trace data. This is useful if you're logging data from multiple applications to the same Application Insights resource, and you want to differentiate between them.
 
@@ -190,7 +217,7 @@ To query trace data for a given service name, query for the `cloud_roleName` pro
 | where cloud_RoleName == "service_name"
 ```
 
-## Enable Tracing for Langchain
+## Enable tracing for Langchain
 
 You can enable tracing for Langchain that follows OpenTelemetry standards as per [opentelemetry-instrumentation-langchain](https://pypi.org/project/opentelemetry-instrumentation-langchain/). To enable tracing for Langchain, install the package `opentelemetry-instrumentation-langchain` using your package manager, like pip:
 
@@ -200,25 +227,13 @@ pip install opentelemetry-instrumentation-langchain
 
 Once necessary packages are installed, you can easily begin to [Instrument tracing in your code](#instrument-tracing-in-your-code).
 
-## Visualize your traces
-
-### View your traces for local debugging
-
-#### Prompty
-
-Using Prompty, you can trace your application with **Open Telemetry**, which offers enhanced visibility and simplified troubleshooting for LLM-based applications. This method adheres to the OpenTelemetry specification, enabling the capture and visualization of an AI application's internal execution details, which improves debugging and enhances the development process. To learn more, see [Debugging Prompty](https://prompty.ai/docs/getting-started/debugging-prompty).
-
-#### Aspire Dashboard
-
-Aspire Dashboard is a free & open-source OpenTelemetry dashboard for deep insights into your apps on your local development machine. To learn more, see [Aspire Dashboard](https://aspiredashboard.com/#start).
-
-### Debugging with traces in Azure AI Foundry portal
+## View traces in Azure AI Foundry portal
 
 In your project, go to `Tracing` to filter your traces as you see fit.
 
-By selecting a trace, I can step through each span and identify issues while observing how my application is responding.
+By selecting a trace, you can step through each span and identify issues while observing how your application is responding. This can help you debug and pinpoint issues in your application.
 
-### View traces in Azure Monitor
+## View traces in Azure Monitor
 
 If you logged traces using the previous code snippet, then you're all set to view your traces in Azure Monitor Application Insights. You can open in Application Insights from **Manage data source** and use the **End-to-end transaction details view** to further investigate.
 

articles/ai-foundry/includes/create-project-fdp.md

@@ -18,11 +18,11 @@ ms.custom: include
 * This project type gives you the best support for:
 
     * Agents
-    * Azure OpenAI models	
-    * Model inferencing
+    * AI Model Inference including Azure Open AI	
     * AI Foundry API that works with agents and across models	
-    * Upload files without needing your own Azure Storage account
+    * Project files (directly upload files and start experimenting)
     * Evaluations
+    * Fine-tuning
     * Playgrounds
 
 ## Prerequisites
@@ -209,5 +209,5 @@ az cognitiveservices account connection show --name {my_project_name} --resource
 
 ## Related content
 
-- [Deploy an enterprise chat web app](../tutorials/deploy-chat-web-app.md)
+- [Quickstart: Get started with Azure AI Foundry](../quickstarts/get-started-code.md?pivots=fdp-project)
 - [Learn more about Azure AI Foundry](../what-is-azure-ai-foundry.md)

articles/ai-foundry/includes/create-second-fdp-project.md

@@ -66,13 +66,14 @@ Your first project (default project) plays a special role and has access to more
 
     # [Azure CLI](#tab/azurecli)
 
-    Use your existing values for {my_resource_group} and {foundry_resource_name} to add another project to the resource:
+    <!-- Use your existing values for {my_resource_group} and {foundry_resource_name} to add another project to the resource:
 
     ```azurecli
      az cognitiveservices account project create --resource-group {my_resource_group} --name {my_project_name} --account-name {foundry_resource_name} 
     ```
-    
-    
+     -->
+    CLI comannds not currently available for creating a [!INCLUDE [fdp-project-name](fdp-project-name.md)].
+
     ---
 
 * If you delete your Foundry resource's default project, the next project created will become the default project. 

articles/ai-foundry/quickstarts/get-started-code.md

@@ -4,7 +4,7 @@ titleSuffix: Azure AI Foundry
 description: This article provides instructions on how to start using the Azure AI Foundry portal and the Azure AI Foundry SDK.
 manager: scottpolly
 ms.service: azure-ai-foundry
-ms.custom: build-2024, devx-track-azurecli, devx-track-python, ignite-2024, update-code3
+ms.custom: build-2024, devx-track-azurecli, devx-track-python, ignite-2024, update-code4
 ms.topic: how-to
 ms.date: 05/12/2025
 ms.reviewer: dantaylo

articles/ai-foundry/toc.yml

@@ -466,6 +466,8 @@ items:
       - name: Vision fine-tuning
         href: ../ai-services/openai/how-to/fine-tuning-vision.md?context=/azure/ai-foundry/context/context
         displayName: finetuning, fine-tuning 
+      - name: Reinforcement fine-tuning
+        href: ../ai-services/openai/how-to/reinforcement-fine-tuning.md?context=/azure/ai-foundry/context/context
       - name: Preference fine-tuning
         href: ../ai-services/openai/how-to/fine-tuning-direct-preference-optimization.md?context=/azure/ai-foundry/context/context
         displayName: finetuning, fine-tuning 

articles/ai-foundry/tutorials/screen-reader.md

@@ -89,7 +89,7 @@ The chat session pane is where you can chat to the model and test out your assis
 
 Azure AI Foundry has two different project types - see [What is Azure AI Foundry?](../what-is-azure-ai-foundry.md#project-types).  The type appears in the  **Type** column in the **All resources** view. In the recent resources picker, the type is in a second line under the project name.
 
-- Listen for **(AI Services)** for a [!INCLUDE [fdp-project-name](../includes/fdp-project-name.md)].  
+- Listen for either **(AI Foundry)** or **Foundry project** for a [!INCLUDE [fdp-project-name](../includes/fdp-project-name.md)].  
 - Listen for **(Hub)** for a [!INCLUDE [hub-project-name](../includes/hub-project-name.md)].
 
 

articles/ai-foundry/what-is-azure-ai-foundry.md

@@ -51,15 +51,14 @@ This table summarizes features available in the two project types:
 | Capability | [!INCLUDE [fdp](includes/fdp-project-name.md)] | [!INCLUDE[hub](includes/hub-project-name.md)] |
 | --- | --- | --- |
 | Agents | ✅ (GA) | ✅ (Preview only) |
-| Azure OpenAI models | ✅ | |
-| Model inferencing | ✅ | |
-| AI Foundry API that works with agents and across models | ✅ | |
-| Common filestore | ✅ | |
-| Project-level isolation of files and outputs | ✅ | ✅ |
+| Azure OpenAI models | ✅ (Native support) | Available via connections |
+| Project files (directly upload files and start experimenting) | ✅ | |
+| Project-level isolation of files and outputs | ✅ | ✅|
 | Evaluations | ✅ | ✅ |
 | Playground | ✅ | ✅ |
 | Prompt flow |  | ✅ |
 | Managed compute  |  | ✅ |
+| Required Azure dependencies | - | Azure Storage account, Azure Key Vault |
 
 ## Navigate in the Azure AI Foundry portal
 
@@ -70,7 +69,7 @@ The left pane is organized around your goals. Generally, as you develop with Azu
 * **Define and explore**. In this stage you define your project goals, and then explore and test models and services against your use case to find the ones that enable you to achieve your goals.
 * **Build and customize**. In this stage, you're actively building solutions and applications with the models, tools, and capabilities you selected. You can also customize models to perform better for your use case by fine-tuning, grounding in your data, and more. Building and customizing might be something you choose to do in the Azure AI Foundry portal, or through code and the Azure AI Foundry SDKs. Either way, a project provides you with everything you need.
   * Once you're actively developing in your project, the **Overview** page shows the things you want easy access to, like your endpoints and keys.
-* **Assess and improve**. In this stage, you're looking for where you can improve your application's performance. You might choose to use tools like tracing to debug your application or compare evaluations to hone in on how you want your application to behave. You can also integrate with safety & security systems so you can be confident when you take your application to production.
+* **Observe and improve**. In this stage, you're looking for where you can improve your application's performance. You might choose to use tools like tracing to debug your application or compare evaluations to hone in on how you want your application to behave. You can also integrate with safety & security systems so you can be confident when you take your application to production.
 
 If you're an admin, or leading a development team, and need to manage the team's resources, project access, quota, and more, you can do that in the Management Center.
 
@@ -110,13 +109,10 @@ Azure AI Foundry is available in most regions where Azure AI services are availa
 
 You can [explore Azure AI Foundry portal (including the model catalog)](./how-to/model-catalog-overview.md) without signing in. 
 
-But for full functionality there are some requirements:
-
-You need an [Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account). 
+But for full functionality, you need an [Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account). 
 
 ## Related content
 
-- [Quickstart: Use the chat playground in Azure AI Foundry portal](quickstarts/get-started-playground.md)
-- [Build a custom chat app in Python using the Azure AI SDK](quickstarts/get-started-code.md)
+- [Quickstart: Get started with Azure AI Foundry](quickstarts/get-started-code.md)
 - [Create a project](./how-to/create-projects.md)
 - [Get started with an AI template](how-to/develop/ai-template-get-started.md)

articles/ai-services/.openpublishing.redirection.ai-services.json

@@ -1149,6 +1149,22 @@
       "source_path_from_root": "/articles/ai-services/speech-service/how-to-async-meeting-transcription.md",
       "redirect_url": "/azure/ai-services/speech-service/multi-device-conversation",
       "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/ai-services/content-understanding/concepts/capabilities.md",
+      "redirect_url": "/azure/ai-services/content-understanding/concepts/analyzer-templates",
+      "redirect_document_id": true
+    },
+    {
+      "source_path_from_root": "/articles/ai-services/content-understanding/concepts/retrieval-augmented-generation.md",
+      "redirect_url": "/azure/ai-services/content-understanding/tutorial/build-rag-solution",
+      "redirect_document_id": true
+    },
+    {
+      "source_path_from_root": "/articles/ai-services/content-understanding/concepts/accuracy-confidence.md",
+      "redirect_url": "/azure/ai-services/content-understanding/concepts/best-practices",
+      "redirect_document_id": true
     }
+
   ]
 }