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 solo proporciona el /openai/v1 punto de conexión.
Autenticación: Aquí se usan ejemplos de 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 gratuita de Azure, que incluye una suscripción de evaluación gratuita.
Tenga uno de los siguientes roles de RBAC de Azure para crear y administrar recursos de Foundry:
- Usuario de Azure AI (rol con privilegios mínimos para el desarrollo)
- Administrador de proyectos de Azure AI (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.
Verificar los requisitos previos
Antes de continuar, confirme:
- [ ] La suscripción de Azure está activa:
az account show - [ ] Tiene el rol RBAC necesario: Consulte Azure Portal → recurso Foundry → Control de acceso (IAM)
- [ ] Runtime de lenguaje instalado:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
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:
Versiones del SDK: El SDK de versión preliminar 2.x tiene como destino el nuevo portal y la API de Foundry. El SDK de disponibilidad general 1.x tiene como destino Foundry clásico. Asegúrese de que los ejemplos que sigue coinciden con el paquete instalado.
| Versión de la SDK | Versión del portal | Situación | Paquete de Python |
|---|---|---|---|
| 2.x (versión preliminar) | Foundry (nuevo) | Preview | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (GA) | Foundry clásico | Estable | azure-ai-projects==1.0.0 |
La biblioteca cliente de proyectos de Azure AI 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 estos comandos para instalar los paquetes de versión preliminar para los proyectos de Foundry.
pip install --pre azure-ai-projects
pip install azure-identity openai
| Versión de la SDK | Versión del portal | Situación | Paquete de Java |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Foundry (nuevo) | Preview | azure-ai-projectsazure-ai-agents |
| Versión de la SDK | Versión del portal | Situación | Paquete de JavaScript |
|---|---|---|---|
| 2.0.0-beta.4 (versión preliminar) | Foundry (nuevo) | Preview | @azure/ai-projects 'prerelease' |
| 1.0.1 | Foundry clásico | Estable | @azure/ai-projects |
| Versión de la SDK | Versión del portal | Situación | Paquete de .NET |
|---|---|---|---|
| 1.2.0-beta.5 (versión preliminar) | Foundry (nuevo) | Preview | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (GA) | Foundry clásico | Estable | Azure.AI.Projects |
La biblioteca cliente de proyectos de Azure AI para Java (versión preliminar) 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
Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
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 de proyectos de Azure AI 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 en versión preliminar para proyectos de Foundry.
npm install @azure/ai-projects@beta @azure/identity dotenv
La biblioteca cliente de proyectos de Azure AI 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 este comando para agregar el paquete Azure.AI.Projects al proyecto de .NET.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
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 las 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 noAzure-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.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
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:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
Qué puede hacer con el SDK de Foundry
- Acceso a los Modelos Foundry, incluido Azure OpenAI
- Usar el servicio Foundry Agent
- Ejecución de evaluaciones en la nube
- 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:
Compruebe que la CLI de Azure está autenticada:
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 Azure AI en el proyecto Foundry.
- Consulte Asignación de 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 # .NET - Verificar la alineación del moniker: el SDK 2.x requiere el portal de Foundry, el SDK 1.x requiere Foundry Clásico.
- Reinstalar 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 los modelos de Azure OpenAI y a los modelos directos de Foundry (a través de la API de Responses). 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 el punto de conexión de Azure OpenAI /openai/v1 directamente.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://cognitiveservices.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 más información, consulte Lenguajes de programación compatibles con Azure OpenAI.
Importante
Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
En el fragmento de código siguiente se muestra cómo usar el punto de conexión de Azure OpenAI /openai/v1 directamente.
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://cognitiveservices.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 más información sobre el uso del SDK de OpenAI, consulte Lenguajes de programación compatibles con Azure OpenAI.
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.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 más información sobre el uso del SDK de OpenAI, consulte Lenguajes de programación compatibles con Azure 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 `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; 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://cognitiveservices.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
Para más información sobre el uso del SDK de OpenAI, consulte Lenguajes de programación compatibles con Azure 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 información general de 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:
Utiliza el punto de conexión de Azure AI Services para acceder a Computer Vision, Seguridad de Contenido, Inteligencia de Documentos, Lenguaje, Traducción y Token Foundry Tools.
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.
En el caso de las herramientas de conversión de voz y traducción, use los puntos de conexión de las tablas siguientes. Sustituya los marcadores de posición por los datos de su recurso.
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 |
| Texto a voz (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/ |
En las secciones siguientes se incluyen vínculos de inicio rápido para los SDK de Foundry Tools e información de referencia.
