Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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 final |
|---|---|---|
| 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> |
| SDK de OpenAI | Los modelos y características más recientes del SDK de OpenAI con la superficie completa de la API de OpenAI. 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 |
| SDK de Foundry Tools | 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 de múltiples agentes 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, o utilice modelos directos de Foundry a través de completaciones de chat.
- Usar SDKs de Foundry Tools al trabajar con servicios de inteligencia artificial 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 de Azure OpenAI proporciona únicamente el endpoint /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.
Prerrequisitos
-
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 el 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.
Verificar 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)
- Entorno de ejecución de lenguaje 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 de lenguaje instalado:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Entorno de ejecución de 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
| Versión de la SDK | Versión del portal | Situación | paquete de Python |
|---|---|---|---|
| 2.x | Foundry (nuevo) | Stable | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (clásico) | Stable | 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 de los proyectos de Foundry.
pip install azure-ai-projects >=2.0.0
| Versión de la SDK | Versión del portal | Situación | paquete de Java |
|---|---|---|---|
| 2.0.0 | Foundry (nuevo) | Stable | azure-ai-projectsazure-ai-agents |
| Versión de la SDK | Versión del portal | Situación | Paquete de JavaScript |
|---|---|---|---|
| 2.0.1 | Foundry (nuevo) | Stable | @azure/ai-projects |
| 1.0.1 | Foundry clásico | Stable | @azure/ai-projects |
| Versión de la SDK | Versión del portal | Situación | paquete de .NET |
|---|---|---|---|
| 2.0.0 (disponibilidad general) | Foundry (nuevo) | Stable | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Foundry clásico | Stable | Azure.AI.Projects |
Importante
No instale Azure.AI.Projects.OpenAI (versión preliminar) junto con Azure.AI.Extensions.OpenAI (GA). Ambos paquetes definen los mismos tipos en espacios de nombres diferentes, lo que provoca errores de referencia ambiguos. Use solo Azure.AI.Extensions.OpenAI para escenarios de agente.
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.
Añade estos paquetes a tu instalación para tus proyectos de Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
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 para proyectos de Foundry.
npm install @azure/ai-projects @azure/identity dotenv
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 necesarios al proyecto de .NET.
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
Uso del SDK de Foundry
El SDK expone dos tipos de cliente porque Foundry y OpenAI tienen diferentes formas de API:
- Cliente del proyecto – se usa para operaciones nativas 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 no Azure-OpenAI hospedados en Foundry). El punto de conexión del proyecto sirve 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.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
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:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
Salida esperada:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Cree un cliente de proyecto:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Cree un cliente de proyecto:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Cree un cliente compatible con OpenAI desde el proyecto:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Cree un cliente de proyecto:
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
Cree un cliente compatible con OpenAI desde el proyecto:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
Qué puede hacer con el SDK de Foundry
- modelos de Access Foundry, incluidos Azure OpenAI
- Usar el servicio Foundry Agent
- Ejecución de evaluaciones por lotes
- Habilitación del seguimiento de aplicaciones
- Ajustar un modelo
- Obtener puntos de conexión y claves para Foundry Tools, 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 Azure CLI se autentica:
az account show az login # if not logged inCompruebe la asignación de roles de RBAC:
- Confirme que cuenta al menos con el rol de Usuario de Azure AI 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.
Errores de coincidencia 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 una de las secciones de idiomas anteriores.
SDK de OpenAI
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 modelos de Azure OpenAI y modelos de acceso directo de Foundry (a través de la Responses API). 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))
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
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.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://ai.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
Para obtener más información sobre el uso del SDK de OpenAI, consulte Azure lenguajes de programación compatibles con OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
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 `ResponsesClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using OpenAI; using OpenAI.Responses; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponsesClient client = openAIClient.GetResponsesClient(); CreateResponseOptions options = new() { Model = deploymentName, InputItems = { ResponseItem.CreateUserMessageItem("What is the size of France in square miles?") }, Temperature = (float)0.7, }; var modelDirectResponse = client.CreateResponse(options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.Value.GetOutputText()}"); #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 framework de agentes 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 endpoints para trabajar con las herramientas de Foundry.
¿Qué punto de conexión deberías usar?
Elija un punto de conexión en función de sus necesidades:
Use el punto de conexión de Azure AI Services para acceder a Computer Vision, 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 de su 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 usan características en desuso de Azure AI Language, como el análisis de sentimientos, la extracción de frases clave, la resumación, la vinculación de entidades, CLU o CQA, planifique 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 forja | Punto final |
|---|---|
| Conversión de voz en texto (estándar) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Text to Speech (neuronal) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Custom Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Puntos finales de traducción
| Herramienta de forja | Punto final |
|---|---|
| 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 forja | Punto final |
|---|---|
| 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 entidad
Características principales con compatibilidad continua: Detección de idioma, detección de PII, Text Analytics para la salud, NER preconstruido y NER personalizado.
Para obtener opciones de migración, consulte Migrate de Language Studio a Microsoft Foundry.
