Nota
L'accés a aquesta pàgina requereix autorització. Podeu provar d'iniciar la sessió o de canviar els directoris.
L'accés a aquesta pàgina requereix autorització. Podeu provar de canviar els directoris.
Visualización actual:
Versión - Cambio a la versión del nuevo portal de Foundry
Un recurso Foundry proporciona acceso unificado a modelos, agentes y herramientas. En este artículo se explica qué SDK y punto de conexión usar para su escenario.
| SDK | Para qué sirve | Punto de conexión |
|---|---|---|
| Foundry SDK | Funcionalidades específicas de Foundry con interfaces compatibles con OpenAI. Incluye acceso a los modelos directos de Foundry a través de la API de respuestas (no finalizaciones de chat). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Los modelos y características más recientes del SDK de OpenAI con la superficie completa de la API de OpenAI, incluidas las incrustaciones. Modelos directos de Foundry disponibles a través de la API de finalizaciones de chat (no respuestas). | https://<resource-name>.openai.azure.com/openai/v1 |
| SDKs de herramientas Foundry | Soluciones precompiladas (Visión, Voz, Seguridad de contenido, etc.). | Puntos de conexión específicos de la herramienta (varía según el servicio). |
| Marco de trabajo del agente | Orquestación multiagente en el código. Independiente de la nube. | Usa el punto de conexión del proyecto mediante el SDK de Foundry. |
Elija el SDK:
- Usar el SDK de Foundry al compilar aplicaciones con agentes, evaluaciones o características específicas de Foundry
- Utilice el SDK de OpenAI cuando se requiera la compatibilidad máxima de OpenAI, al generar inserciones o con modelos directos de Foundry mediante autocompletado de chat
- Usar SDKs de Foundry Tools al trabajar con servicios de IA específicos (Visión, Voz, Lenguaje, etc.)
- Uso de Agent Framework al compilar sistemas multiagente en código (orquestación local)
Nota
Tipos de recursos: Un recurso Foundry proporciona todos los puntos de conexión enumerados anteriormente. Un recurso Azure de OpenAI solo proporciona el punto de conexión de /openai/v1.
Authentication: Ejemplos aquí usan Microsoft Entra ID (DefaultAzureCredential). Las claves de API funcionan en /openai/v1. Pase la clave como api_key en lugar de un proveedor de tokens.
Requisitos previos
-
Una cuenta de Azure con una suscripción activa. Si no tiene una, cree una cuenta de free Azure, que incluye una suscripción de evaluación gratuita.
Tenga uno de los siguientes roles de RBAC Azure para crear y administrar recursos de Foundry:
- Usuario de IA de Azure (rol con privilegios mínimos para el desarrollo)
- Azure AI Project Manager (para administrar proyectos de Foundry)
- Colaborador o Propietario (para permisos de nivel de suscripción)
Para obtener más información sobre los permisos de cada rol, consulte Control de acceso basado en roles para Microsoft Foundry.
Instale los entornos de ejecución de lenguaje necesarios, las herramientas globales y las extensiones de VS Code, tal como se describe en Preparación del entorno de desarrollo.
Importante
Antes de empezar, asegúrese de que el entorno de desarrollo esté listo.
Este artículo se centra en pasos específicos del escenario , como la instalación del SDK, la autenticación y la ejecución de código de ejemplo.
Comprobación de los requisitos previos
Antes de continuar, confirme:
- Azure suscripción está activa:
az account show - Tiene el rol de RBAC necesario: consulte Azure Portal → Recurso de Foundry → Control de acceso (IAM)
- Idioma de tiempo de ejecución instalado:
- Python:
python --version(≥3.8)
- Python:
- Entorno de ejecución de lenguaje instalado.
- Node.js:
node --version(≥18)
- Node.js:
- Entorno de ejecución del lenguaje instalado:
- .NET:
dotnet --version(≥6.0)
- .NET:
- El entorno de ejecución del lenguaje instalado.
- Java:
java --version(≥11)
- Java:
Foundry SDK
El SDK de Foundry se conecta a un único punto de conexión de proyecto que proporciona acceso a las funcionalidades de Foundry más populares:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Nota
Si su organización usa un subdominio personalizado, reemplace por <resource-name><your-custom-subdomain> en la dirección URL del punto de conexión.
Este enfoque simplifica la configuración de la aplicación. En lugar de administrar varios puntos de conexión, configure uno.
Instalación del SDK
Nota
Este artículo se aplica a un proyecto de Foundry. El código que se muestra aquí no funciona para un proyecto basado en un hub. Para obtener más información, vea Tipos de proyectos.
Nota
Versiones del SDK: En este artículo se describe la instalación del SDK 1.x. Asegúrese de que los ejemplos que sigue coinciden con el paquete instalado. Cambie a la nueva documentación del portal de Foundry para ver el artículo de la versión 2.x.
| Versión del SDK | Versión del portal | Estado | paquete de Python |
|---|---|---|---|
| 2.x | Foundry (nuevo) | Estable | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (clásico) | Estable | azure-ai-projects==1.0.0 |
La biblioteca cliente Azure AI Projects para Python es una biblioteca unificada que permite usar varias bibliotecas cliente juntas mediante la conexión a un único punto de conexión de proyecto.
Ejecute este comando para instalar los paquetes 1.x para proyectos clásicos de Foundry.
pip install openai azure-identity azure-ai-projects==1.0.0
| Versión del SDK | Versión del portal | Estado | paquete de Java |
|---|---|---|---|
| 2.0.0 | Fundición (nueva) | Estable | azure-ai-projectsazure-ai-agents |
| Versión del SDK | Versión del portal | Estado | Paquete de JavaScript |
|---|---|---|---|
| 2.0.1 | Foundry (nuevo) | Estable | @azure/ai-projects |
| 1.0.1 | Foundry clásico | Estable | @azure/ai-projects |
| Versión del SDK | Versión del portal | Estado | paquete de .NET |
|---|---|---|---|
| 2.0.0-beta.1 (versión preliminar) | Fundición (nueva) | Vista previa | Azure.AI.ProjectsAzure.AI.Projects.OpenAI |
| 1.1.0 (GA) | Foundry clásico | Estable | Azure.AI.Projects |
La biblioteca cliente Azure AI Projects para Java es una biblioteca unificada que permite usar varias bibliotecas cliente juntas mediante la conexión a un único punto de conexión de proyecto.
Importante
El paquete Java azure-ai-projects no tiene una versión de disponibilidad general 1.x. Los ejemplos de código de las secciones de Java usan directamente el paquete azure-ai-inference, que está en desuso y se retirará el 30 de mayo de 2026.
Para el SDK de proyectos 2.x, cambie a la nueva documentación del portal de Foundry.
Agregue estas dependencias a su archivo Maven pom.xml para proyectos de Foundry clásicos.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-inference</artifactId>
<version>1.0.0-beta.6</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.2</version>
</dependency>
La biblioteca cliente Azure AI Projects para JavaScript es una biblioteca unificada que permite usar varias bibliotecas cliente juntas mediante la conexión a un único punto de conexión de proyecto.
Ejecute este comando para instalar los paquetes de JavaScript 1.x para proyectos clásicos de Foundry.
npm install @azure/ai-projects@1.0.1 @azure/identity
La biblioteca cliente Azure AI Projects para .NET es una biblioteca unificada que permite usar varias bibliotecas cliente juntas mediante la conexión a un único punto de conexión de proyecto.
Ejecute estos comandos para agregar los paquetes 1.x Azure SDK de IA para proyectos clásicos de Foundry.
# Add 1.x Azure AI SDK packages
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --version 1.1.0
dotnet add package Azure.AI.Agents.Persistent --version 1.1.0
dotnet add package Azure.AI.Inference
Uso del SDK de Foundry
El SDK expone dos tipos de cliente porque Foundry y OpenAI tienen diferentes formas de API:
- Project client – Utilícelo para operaciones propias de Foundry en las que OpenAI no tiene ningún equivalente. Ejemplos: enumerar conexiones, recuperar propiedades del proyecto, habilitar el seguimiento.
-
Cliente compatible con OpenAI : se usa para la funcionalidad foundry que se basa en los conceptos de OpenAI. La API de respuestas, los agentes, las evaluaciones y el ajuste preciso usan patrones de solicitud y respuesta de estilo OpenAI. Este cliente también proporciona acceso a los modelos directos de Foundry (modelos noAzure-OpenAI hospedados en Foundry). El punto de conexión del proyecto gestiona este tráfico en la ruta
/openai.
La mayoría de las aplicaciones usan ambos clientes. Use el cliente del proyecto para configurar y configurar y, a continuación, use el cliente compatible con OpenAI para ejecutar agentes, evaluaciones y modelos de llamada (incluidos los modelos directos de Foundry).
Cree un cliente de proyecto:
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential(),
)
Cree un cliente compatible con OpenAI desde el proyecto:
models = project_client.get_openai_client(api_version="2024-10-21")
chat_responses = models.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the size of France in square miles?"},
],
)
print(chat_responses.choices[0].message.content)
Cree un cliente de proyecto:
package com.azure.ai.foundry.samples;
import com.azure.ai.inference.ChatCompletionsClient;
import com.azure.ai.inference.ChatCompletionsClientBuilder;
import com.azure.ai.inference.models.ChatCompletions;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.credential.TokenCredential;
import com.azure.core.exception.HttpResponseException;
import com.azure.core.util.logging.ClientLogger;
import com.azure.identity.DefaultAzureCredentialBuilder;
String prompt = "What best practices should I follow when asking an AI model to review Java code?";
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
.credential(credential)
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
ChatCompletions completions = client.complete(prompt);
String content = completions.getChoice().getMessage().getContent();
System.out.println("\nResponse from AI assistant:\n" + content);
Cree un cliente de proyecto:
const endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deployment = "gpt-4o";
const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
Cree un cliente compatible con OpenAI desde el proyecto:
const client = await project.getAzureOpenAIClient({
// The API version should match the version of the Azure OpenAI resource
apiVersion: "2024-12-01-preview"
});
const chatCompletion = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(chatCompletion.choices[0].message.content);
Cree un cliente de proyecto:
using System.ClientModel.Primitives;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.Identity;
using OpenAI.Chat;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
Cree un cliente compatible con OpenAI desde el proyecto:
ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
{
throw new InvalidOperationException("Invalid URI.");
}
uri = new Uri($"https://{uri.Host}");
const string modelDeploymentName = "gpt-4o";
AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
ChatClient chatClient = azureOpenAIClient.GetChatClient(deploymentName: modelDeploymentName);
Console.WriteLine("Complete a chat");
ChatCompletion result = chatClient.CompleteChat("List all the rainbow colors");
Console.WriteLine(result.Content[0].Text);
Qué puede hacer con el SDK de Foundry
- modelos de Access Foundry, incluidos Azure OpenAI
- Uso del Servicio Foundry Agent
- Ejecución de evaluaciones en la nube
- Habilitación del seguimiento de aplicaciones
- Afina un modelo
- Obtención de puntos de conexión y claves para las herramientas de Foundry, la orquestación local y mucho más
Solución de problemas
Errores de autenticación
Si ve DefaultAzureCredential failed to retrieve a token:
Verify CLI de Azure se autentica:
az account show az login # if not logged inCompruebe la asignación de roles de RBAC:
- Confirme que tiene al menos el rol de Usuario de IA de Azure en el proyecto Foundry.
- Consulte Asignar roles de Azure
Para la identidad administrada en producción:
- Asegúrese de que la identidad administrada tiene asignado el rol adecuado.
- Consulte Configuración de identidades administradas.
Errores de configuración del punto de conexión
Si ve Connection refused o 404 Not Found:
- Comprobación de que los nombres de recursos y proyectos coinciden con la implementación real
-
Comprobar el formato de dirección URL del punto de conexión: debe ser
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Para subdominios personalizados: reemplace
<resource-name>por el subdominio personalizado.
Incompatibilidad de versiones del SDK
Si se produce un error en los ejemplos de código con AttributeError o ModuleNotFoundError:
Compruebe la versión del SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NETReinstalar con marcas de versión correctas: consulte los comandos de instalación en cada sección de idioma anterior.
OpenAI SDK
Use el SDK de OpenAI cuando desee la superficie completa de la API de OpenAI y la compatibilidad máxima del cliente. Este punto de conexión proporciona acceso a los modelos de Azure OpenAI y a los modelos directos de Foundry (a través de la API de finalizaciones de chat). No proporciona acceso a características específicas de Foundry, como agentes y evaluaciones.
En el fragmento de código siguiente se muestra cómo usar directamente el punto de conexión de Azure OpenAI /openai/v1.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
base_url = "https://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
Para obtener más información, consulte Azure lenguajes de programación compatibles con OpenAI. Salida esperada:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
Para obtener más información, consulte Azure lenguajes de programación compatibles con OpenAI
Importante
Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.
En el fragmento de código siguiente se muestra cómo usar directamente el punto de conexión de Azure OpenAI /openai/v1.
import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.models.ChatChoice;
import com.azure.ai.openai.models.ChatCompletions;
import com.azure.ai.openai.models.ChatCompletionsOptions;
import com.azure.ai.openai.models.ChatRequestAssistantMessage;
import com.azure.ai.openai.models.ChatRequestMessage;
import com.azure.ai.openai.models.ChatRequestSystemMessage;
import com.azure.ai.openai.models.ChatRequestUserMessage;
import com.azure.ai.openai.models.ChatResponseMessage;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Configuration;
import java.util.ArrayList;
import java.util.List;
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(defaultCredential)
.endpoint("{endpoint}")
.buildClient();
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant."));
chatMessages.add(new ChatRequestUserMessage("What is the speed of light?"));
ChatCompletions chatCompletions = client.getChatCompletions(deploymentName, new ChatCompletionsOptions(chatMessages));
System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
ChatResponseMessage message = choice.getMessage();
System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
System.out.println("Message:");
System.out.println(message.getContent());
Para obtener más información sobre el uso del SDK de OpenAI, consulte Azure lenguajes de programación compatibles con OpenAI.
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const deployment = "gpt-4o";
const endpoint = "https://<resource-name>.openai.azure.com";
const scope = "https://ai.azure.com/.default";
const apiVersion = "2024-04-01-preview";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const options = { azureADTokenProvider, deployment, apiVersion, endpoint };
const client = new AzureOpenAI(options);
const result = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(result.choices[0].message.content);
Para obtener más información sobre el uso del SDK de OpenAI, consulte Azure lenguajes de programación compatibles con OpenAI.
- Instale el paquete OpenAI: ejecute este comando para agregar la biblioteca cliente de OpenAI al proyecto de .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ChatClient` for the Azure OpenAI v1 endpoint. ```csharp using System.ClientModel.Primitives; using Azure.Identity; using OpenAI; using OpenAI.Chat; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string modelDeploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ChatClient chatClient = openAIClient.GetChatClient(modelDeploymentName); ChatCompletion completion = await chatClient.CompleteChatAsync( [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("How many feet are in a mile?") ]); Console.WriteLine(completion.Content[0].Text); #pragma warning restore OPENAI001
Para obtener más información sobre el uso del SDK de OpenAI, consulte Azure lenguajes de programación compatibles con OpenAI.
Uso del marco del agente para la orquestación local
Microsoft Agent Framework es un SDK de código abierto para compilar sistemas multiagente en código (por ejemplo, .NET y Python) con una interfaz independiente del proveedor de nube.
Use Agent Framework cuando quiera definir y organizar los agentes localmente. Adíptelo con el SDK de Foundry cuando desee que esos agentes se ejecuten en modelos foundry o cuando quiera que Agent Framework organice los agentes hospedados en Foundry.
Para obtener más información, consulte la introducción a Microsoft Agent Framework.
SDK de herramientas de fundición
Foundry Tools (anteriormente Azure AI Services) son soluciones de punto precompiladas con SDK dedicados. Utilice los siguientes puntos de conexión para trabajar con las herramientas de Foundry.
¿Qué punto de conexión deberías utilizar?
Elija un punto de conexión en función de sus necesidades:
Utilice el punto de conexión de Azure AI Services para acceder a Visión por Computadora, Seguridad de Contenido, Inteligencia de Documentos, Lenguaje, Traducción y Herramientas de Token Foundry.
Punto de conexión de Foundry Tools: https://<your-resource-name>.cognitiveservices.azure.com/
Nota
Los puntos de conexión utilizan el nombre del recurso o un subdominio personalizado. Si su organización configura un subdominio personalizado, reemplace por your-resource-nameyour-custom-subdomain en todos los ejemplos de puntos de conexión.
Si sus cargas de trabajo utilizan características en desuso de Lenguaje de Azure AI (por ejemplo, análisis de sentimientos, extracción de frases clave, resumen, vinculación de entidades, CLU o CQA), considere migrar a las alternativas de Microsoft Foundry. Para el nuevo desarrollo, considere la posibilidad de usar el SDK de Foundry o el punto de conexión compatible con OpenAI, como se ha descrito anteriormente en este artículo. Consulte Migrar de Language Studio a Microsoft Foundry.
En el caso de las herramientas de conversión de voz y traducción, use los puntos de conexión de las tablas siguientes. Reemplace los marcadores de posición por los nombres de recursos.
Puntos de conexión de voz
| Herramienta de fundición | Punto de conexión |
|---|---|
| Conversión de voz en texto (estándar) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Texto a voz (Neuronal) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Voz personalizada | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Puntos de conexión de traducción
| Herramienta de fundición | Punto de conexión |
|---|---|
| Traducción de texto | https://api.cognitive.microsofttranslator.com/ |
| Traducción de documentos | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Puntos de conexión de idioma
| Herramienta de fundición | Punto de conexión |
|---|---|
| Análisis de texto | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com |
Importante
El 20 de marzo de 2027, Azure Language Studio se retirará y migrará a Microsoft Foundry; todas las funcionalidades y futuras mejoras estarán disponibles en Microsoft Foundry.
El 31 de marzo de 2029, se retirarán las siguientes funcionalidades de lenguaje de Azure (finalización del soporte técnico). Antes de esa fecha, los usuarios deben migrar las cargas de trabajo existentes e incorporar nuevos proyectos a Microsoft modelos Foundry para mejorar la comprensión del lenguaje natural y la integración simplificada de aplicaciones:
- Extracción de frases clave
- Análisis de sentimiento y minería de opiniones
- Clasificación de texto personalizada
- Comprensión del Lenguaje Conversacional (CLU)
- Respuesta a preguntas personalizadas (CQA)
- Flujo de trabajo de orquestación
- Resumen (extractivo y abstracto, para documentos y conversaciones)
- Vinculación de entidades
Características principales con compatibilidad continua: detección de idioma, detección de PII, Text Analytics para salud, NER preconstruido y NER personalizado.
Para obtener opciones de migración, consulte Migrate de Language Studio a Microsoft Foundry.
