Biblioteca cliente de Azure AI Projects para JavaScript: versión 1.0.1

La biblioteca cliente de AI Projects proporciona un acceso sencillo a los recursos del proyecto de Azure AI Foundry. Utilícelo para:

Cree y ejecute agentes mediante la .agents propiedad en el cliente.
Obtenga un cliente AzureOpenAI mediante el .inference.azureOpenAI método.
Enumere los modelos de IA implementados en su proyecto de Foundry mediante las .deployments operaciones.
Enumere los recursos de Azure conectados en el proyecto de Foundry mediante las .connections operaciones.
Cargue documentos y cree conjuntos de datos para hacer referencia a ellos mediante las .datasets operaciones.
Cree y enumere índices de búsqueda mediante las .indexes operaciones.
Habilite el seguimiento de OpenTelemetry mediante la enable_telemetry función.

Documentación del | productoMuestras | Paquete (npm) | Documentación de referencia de | la APICódigo fuente del SDK

Tabla de contenido

Empezar
Conceptos clave
- Creación y autenticación del cliente
Ejemplos
Solución de problemas
- Excepciones
- problemas de informes
Pasos siguientes
de contribución

Cómo empezar

Prerrequisito

Autorización

Se necesita el ID de Entra para autenticar al cliente. La aplicación necesita un objeto que implemente la interfaz
TokenCredential. Los ejemplos de código aquí usan DefaultAzureCredential. Para que funcione, necesitará lo siguiente:
- Rol de Contributor. El rol asignado se puede realizar a través de la pestaña "Control de acceso (IAM)" del recurso del proyecto de Azure AI en Azure Portal. Obtenga más información sobre las asignaciones de roles aquí.
- de la CLI de Azure instalada.
- Ha iniciado sesión en su cuenta de Azure mediante la ejecución de az login.
- Tenga en cuenta que si tiene varias suscripciones de Azure, la suscripción que contiene el recurso de Proyecto de Azure AI debe ser la suscripción predeterminada. Ejecute az account list --output table para enumerar toda la suscripción y ver cuál es el valor predeterminado. Ejecute az account set --subscription "Your Subscription ID or Name" para cambiar la suscripción predeterminada.

Instalación del paquete

npm install @azure/ai-projects @azure/identity

Conceptos clave

Creación y autenticación del cliente

Para construir un AIProjectsClient, el se puede obtener desde el endpointpunto de conexión. A continuación, asumiremos que la variable AZURE_AI_PROJECT_ENDPOINT_STRING de entorno se definió para mantener este valor:

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = process.env["AZURE_AI_PROJECT_ENDPOINT_STRING"] || "<project endpoint string>";
const client = new AIProjectClient(endpoint, new DefaultAzureCredential());

El cliente utiliza la versión v1de la API, consulte la documentación de la API para obtener más información sobre las funciones compatibles.

Ejemplos

Realización de operaciones de agente

La .agents propiedad de la AIProjectClient le da acceso a un autenticado AgentsClient desde el azure-ai-agents paquete. A continuación mostramos cómo crear un agente y eliminarlo. Para ver lo que puede hacer con el agent paquete que ha creado, consulte los numerosos ejemplos asociados al azure-ai-agents paquete.

const agent = await project.agents.createAgent("gpt-4o", {
  name: "my-agent",
  instructions: "You are a helpful agent",
});
console.log(`Created agent, agent ID : ${agent.id}`);

// Do something with your Agent!
// See samples here https://github.com/Azure/azure-sdk-for-js/tree/@azure/ai-projects_1.0.1/sdk/ai/ai-agents/samples
await project.agents.deleteAgent(agent.id);
console.log(`Deleted agent, agent ID: ${agent.id}`);

Obtención de un cliente de AzureOpenAI autenticado

El proyecto de Azure AI Foundry puede tener uno o varios modelos de OpenAI implementados que admitan la finalización de chats. Use el código siguiente para obtener un AzureOpenAI autenticado del paquete openai y ejecutar una llamada de finalización de chat.

Ejecute el código a continuación. Aquí suponemos que deploymentName (str) está definido. Es el nombre de implementación de un modelo de IA en su proyecto de Foundry. Como se muestra en la pestaña "Modelos + puntos finales", en la columna "Nombre".

Actualice el api_version valor con uno que se encuentre en la fila "Plano de datos - inferencia" de esta tabla.

También tiene la opción (no se muestra) de especificar explícitamente el nombre de la conexión de Azure OpenAI en el proyecto de AI Foundry, que el inference.azureOpenAI método usará para obtener el punto de conexión de inferencia y las credenciales de autenticación. Si no está presente, se utilizará la conexión predeterminada de Azure OpenAI.

const client = await project.inference.azureOpenAI({
  // The API version should match the version of the Azure OpenAI resource.
  apiVersion: "2024-10-21",
});
const response = await client.chat.completions.create({
  model: deploymentName,
  messages: [{ role: "user", content: "How many feet are in a mile?" }],
});
console.log("response = ", JSON.stringify(response, null, 2));

Consulte la carpeta "inference" en los ejemplos de paquete para obtener ejemplos adicionales.

Operaciones de despliegues

En el código siguiente se muestran algunas operaciones de implementación, que le permiten enumerar los modelos de IA implementados en sus proyectos de AI Foundry. Estos modelos se pueden ver en la pestaña "Modelos + puntos finales" de su proyecto de AI Foundry. Los ejemplos completos se pueden encontrar en la carpeta "deployment" en los ejemplos del paquete.

import { ModelDeployment } from "@azure/ai-projects";

const modelPublisher = process.env["MODEL_PUBLISHER"] || "<model publisher>";
console.log("List all deployments:");
const deployments: ModelDeployment[] = [];
const properties: Array<Record<string, string>> = [];

for await (const deployment of project.deployments.list()) {
  // Check if this is a ModelDeployment (has the required properties)
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    deployments.push(deployment);
    properties.push({
      name: deployment.name,
      modelPublisher: deployment.modelPublisher,
      modelName: deployment.modelName,
    });
  }
}
console.log(`Retrieved deployments: ${JSON.stringify(properties, null, 2)}`);

// List all deployments by a specific model publisher (assuming we have one from the list)
console.log(`List all deployments by the model publisher '${modelPublisher}':`);
const filteredDeployments: ModelDeployment[] = [];
for await (const deployment of project.deployments.list({
  modelPublisher,
})) {
  // Check if this is a ModelDeployment
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    filteredDeployments.push(deployment);
  }
}
console.log(
  `Retrieved ${filteredDeployments.length} deployments from model publisher '${modelPublisher}'`,
);

// Get a single deployment by name
if (deployments.length > 0) {
  const deploymentName = deployments[0].name;
  console.log(`Get a single deployment named '${deploymentName}':`);
  const singleDeployment = await project.deployments.get(deploymentName);
  console.log(`Retrieved deployment: ${JSON.stringify(singleDeployment, null, 2)}`);
}

Operaciones de conexión

En el código siguiente se muestran algunas operaciones de conexión, que permiten enumerar los recursos de Azure conectados a los proyectos de AI Foundry. Estas conexiones se pueden ver en el "Centro de gestión", en la pestaña "Recursos conectados" de su proyecto AI Foundry. Los ejemplos completos se pueden encontrar en la carpeta "connections" de los ejemplos del paquete.

import { Connection } from "@azure/ai-projects";

// List the details of all the connections
const connections: Connection[] = [];
const connectionNames: string[] = [];
for await (const connection of project.connections.list()) {
  connections.push(connection);
  connectionNames.push(connection.name);
}
console.log(`Retrieved connections: ${connectionNames}`);

// Get the details of a connection, without credentials
const connectionName = connections[0].name;
const connection = await project.connections.get(connectionName);
console.log(`Retrieved connection ${JSON.stringify(connection, null, 2)}`);

const connectionWithCredentials = await project.connections.getWithCredentials(connectionName);
console.log(
  `Retrieved connection with credentials ${JSON.stringify(connectionWithCredentials, null, 2)}`,
);

// List all connections of a specific type
const azureAIConnections: Connection[] = [];
for await (const azureOpenAIConnection of project.connections.list({
  connectionType: "AzureOpenAI",
  defaultConnection: true,
})) {
  azureAIConnections.push(azureOpenAIConnection);
}
console.log(`Retrieved ${azureAIConnections.length} Azure OpenAI connections`);

// Get the details of a default connection
const defaultConnection = await project.connections.getDefault("AzureOpenAI", true);
console.log(`Retrieved default connection ${JSON.stringify(defaultConnection, null, 2)}`);

Operaciones de conjuntos de datos

En el código siguiente se muestran algunas operaciones del conjunto de datos. Las muestras completas se pueden encontrar en la carpeta "datasets" en las muestras del paquete.

import { DatasetVersionUnion } from "@azure/ai-projects";

const VERSION1 = "1.0";
const VERSION2 = "2.0";
const VERSION3 = "3.0";

// sample files to use in the demonstration
const sampleFolder = "sample_folder";
// Create a unique dataset name for this sample run
const datasetName = `sample-dataset-basic`;
console.log("Upload a single file and create a new Dataset to reference the file.");
console.log("Here we explicitly specify the dataset version.");

const dataset1 = await project.datasets.uploadFile(
  datasetName,
  VERSION1,
  path.join(__dirname, sampleFolder, "sample_file1.txt"),
);
console.log("Dataset1 created:", JSON.stringify(dataset1, null, 2));

const credential = project.datasets.getCredentials(dataset1.name, dataset1.version, {});
console.log("Credential for the dataset:", credential);
console.log(
  "Upload all files in a folder (including subfolders) to the existing Dataset to reference the folder.",
);
console.log("Here again we explicitly specify a new dataset version");
const dataset2 = await project.datasets.uploadFolder(
  datasetName,
  VERSION2,
  path.join(__dirname, sampleFolder),
);
console.log("Dataset2 created:", JSON.stringify(dataset2, null, 2));
console.log(
  "Upload a single file to the existing dataset, while letting the service increment the version",
);
const dataset3 = await project.datasets.uploadFile(
  datasetName,
  VERSION3,
  path.join(__dirname, sampleFolder, "sample_file2.txt"),
);
console.log("Dataset3 created:", JSON.stringify(dataset3, null, 2));

console.log("Get an existing Dataset version `1`:");
const datasetVersion1 = await project.datasets.get(datasetName, VERSION1);
console.log("Dataset version 1:", JSON.stringify(datasetVersion1, null, 2));
console.log(`Listing all versions of the Dataset named '${datasetName}':`);
const datasetVersions = await project.datasets.listVersions(datasetName);
for await (const version of datasetVersions) {
  console.log("List versions:", version);
}
console.log("List latest versions of all Datasets:");
const latestDatasets = project.datasets.list();
for await (const dataset of latestDatasets) {
  console.log("List datasets:", dataset);
}
// List the details of all the datasets
const datasets = project.datasets.listVersions(datasetName);
const allDatasets: DatasetVersionUnion[] = [];
for await (const dataset of datasets) {
  allDatasets.push(dataset);
}
console.log(`Retrieved ${allDatasets.length} datasets`);
console.log("Delete all Datasets created above:");
await project.datasets.delete(datasetName, VERSION1);
await project.datasets.delete(datasetName, VERSION2);
await project.datasets.delete(datasetName, dataset3.version);
console.log("All specified Datasets have been deleted.");

Operaciones de índices

En el código siguiente se muestran algunas operaciones de índices. Las muestras completas se pueden encontrar en la carpeta "indexes" en las muestras del paquete.

import { AzureAISearchIndex } from "@azure/ai-projects";

const indexName = "sample-index";
const version = "1";
const azureAIConnectionConfig: AzureAISearchIndex = {
  name: indexName,
  type: "AzureSearch",
  version,
  indexName,
  connectionName: "sample-connection",
};

// Create a new Index
const newIndex = await project.indexes.createOrUpdate(indexName, version, azureAIConnectionConfig);
console.log("Created a new Index:", newIndex);
console.log(`Get an existing Index version '${version}':`);
const index = await project.indexes.get(indexName, version);
console.log(index);
console.log(`Listing all versions of the Index named '${indexName}':`);
const indexVersions = project.indexes.listVersions(indexName);
for await (const indexVersion of indexVersions) {
  console.log(indexVersion);
}
console.log("List all Indexes:");
const allIndexes = project.indexes.list();
for await (const i of allIndexes) {
  console.log("Index:", i);
}
console.log("Delete the Index versions created above:");
await project.indexes.delete(indexName, version);

Solución de problemas

Excepciones

Los métodos cliente que realizan llamadas de servicio generan un restError para una respuesta de código de estado HTTP no correcta del servicio. El code de la excepción contendrá el código de estado de respuesta HTTP. El error.message de la excepción contiene un mensaje detallado que puede resultar útil para diagnosticar el problema:

import { isRestError } from "@azure/core-rest-pipeline";

try {
  const result = await project.connections.list();
} catch (e) {
  if (isRestError(e)) {
    console.log(`Status code: ${e.code}`);
    console.log(e.message);
  } else {
    console.error(e);
  }
}

Por ejemplo, cuando se proporcionan credenciales incorrectas:

Status code: 401 (Unauthorized)
Operation returned an invalid status 'Unauthorized'

Información sobre los problemas

Para notificar problemas con la biblioteca cliente o solicitar características adicionales, abra un problema de GitHub aquí

Pasos siguientes

Vea la carpeta de ejemplos de paquete , que contiene código totalmente ejecutable.

Contribución

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más información, visite https://cla.microsoft.com.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com con preguntas o comentarios adicionales.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-10-15