Nota
O acceso a esta páxina require autorización. Pode tentar iniciar sesión ou modificar os directorios.
O acceso a esta páxina require autorización. Pode tentar modificar os directorios.
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. 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 |
| Foundry Tools SDKs | 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 Agnóstico 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
- Use el SDK de OpenAI cuando se requiera la compatibilidad máxima de OpenAI, o utilizando modelos directos de Foundry a través de completaciones de chat.
- Utilice SDKs de Foundry Tools al trabajar con servicios específicos de inteligencia artificial (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.
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 Azure AI (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.
Comprobación de los requisitos previos
Antes de continuar, confirme:
- Azure suscripción está activa:
az account show - Tiene el rol RBAC necesario: Compruebe el portal de Azure → Recurso 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
Nota
Este artículo se aplica a un proyecto Foundry. El código que se muestra aquí no funciona para un proyecto centrado 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 | Foundry (nuevo) | 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 edición clásica | Estable | @azure/ai-projects |
| Versión del SDK | Versión del portal | Estado | paquete de .NET |
|---|---|---|---|
| 2.0.0-beta.1 (versión preliminar) | Foundry (nuevo) | Vista previa | Azure.AI.ProjectsAzure.AI.Projects.OpenAI |
| 1.1.0 (GA) | Foundry edición clásica | 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 al archivo pom.xml de Maven para los proyectos clásicos de Foundry.
<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:
- Cliente del proyecto: utilizar para operaciones nativas de Foundry en las que OpenAI no tiene ningún análogo. 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.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
- Afinar un modelo
- Obtener puntos de conexión y claves para herramientas de Foundry, 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 AI 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.
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 las secciones anteriores de cada idioma.
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 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 endpoints para trabajar con la herramienta de Foundry.
¿Qué endpoint debe 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 Contenidos, 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 usan 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 usan características de Lenguaje de Azure AI que están quedando obsoletas, como el análisis de sentimientos, la extracción de frases clave, el resumen, la vinculación de entidades, CLU o CQA, planifique la migración 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 el artículo 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. Reemplaza los marcadores de posición con la información de tu recurso.
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 (neural) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Voz personalizada | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Puntos finales 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 precompilado y NER personalizado.
Para obtener opciones de migración, consulte Migrate de Language Studio a Microsoft Foundry.
