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.
Nota:
Este documento hace referencia al portal de Microsoft Foundry (clásico).
🔍 Consulte la documentación de Microsoft Foundry (nuevo) para obtener información sobre el nuevo portal.
Un recurso de 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 Completaciones 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 toda la interfaz 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 a través del 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 Azure 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.
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 Azure AI (rol de mínimos privilegios 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 Role-based access control for 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 RBAC necesario: Compruebe el Azure Portal → Recurso Foundry → Control de acceso (IAM)
- [ ] Entorno de ejecución del 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 del proyecto que proporciona acceso a las capacidades 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 Foundry. El código que se muestra aquí no funciona para un proyecto basado en hub. Para más información, vea Tipos de proyectos.
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 | 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 endpoint de proyecto.
Ejecute este comando para instalar los paquetes estables para los proyectos clásicos de Foundry.
pip install openai azure-identity azure-ai-projects==1.0.0
| 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 | Stable | @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 | Stable | Azure.AI.Projects |
La biblioteca cliente Azure AI Projects 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 obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.
Agregue estos paquetes a la instalación de proyectos clásicos de Foundry.
package com.azure.ai.foundry.samples;
import com.azure.ai.projects;
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;
La biblioteca cliente Azure AI Projects para JavaScript es una biblioteca unificada que permite la utilización conjunta de múltiples bibliotecas cliente conectándose a un único punto de conexión del proyecto.
Ejecute este comando para instalar los paquetes de JavaScript actuales para proyectos clásicos de Foundry.
npm install @azure/ai-projects @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 del SDK de IA de Azure para proyectos clásicos de Foundry.
# Add Azure AI SDK packages
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Agents.Persistent
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:
- Cliente de proyecto – se usa para operaciones nativas de Foundry en las que OpenAI no tiene ningún equivalente. Ejemplos: enumerar conexiones, recuperar propiedades de 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 ofrece acceso a los modelos disponibles directamente de Foundry (modelos que no son de Azure-OpenAI y que se alojan en Foundry). El endpoint 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 la configuración, y a continuación, use el cliente compatible con OpenAI para ejecutar agentes, evaluaciones y realizar llamadas a modelos (incluidos los modelos de Foundry directos).
Crear un cliente del proyecto:
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential(),
)
```**Create an OpenAI-compatible client from your project:**
```python
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)
Crear un cliente del 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);
Crear un cliente del 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());
Crear un cliente compatible con OpenAI desde su 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);
Crear un cliente del proyecto:
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
Crear un cliente compatible con OpenAI desde su 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, incluido Azure OpenAI
- Use el servicio Foundry Agent Service
- 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:
Verify Azure CLI 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:
- Verifique que los nombres de recursos y proyectos coincidan con la implementación real
-
Comprueba el formato del URL del endpoint: Debería 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
Utilice el SDK de OpenAI cuando desee tener acceso a toda la funcionalidad de la API de OpenAI y garantizar la máxima compatibilidad con el cliente. Este punto de conexión proporciona acceso a los modelos de Azure OpenAI y los modelos directos de Foundry (a través de la API de finalizaciones de chat). No proporciona acceso a las 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://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))
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) 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 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 } from "@azure/identity";
const deployment = "gpt-4o"
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const apiVersion = "2024-04-01-preview";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const options = { azureADTokenProvider, deployment, apiVersion }
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 a la .NET project.
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 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:
Utilice el punto de conexión de Azure AI Services para acceder a Visión Artificial, seguridad de contenido, inteligencia de documentos, lenguaje, traducción y herramientas de Token Foundry.
Punto de conexión de herramientas de fundición: 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. 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/ |
En las secciones siguientes se incluyen vínculos de inicio rápido para los SDK de Foundry Tools e información de referencia.
