Compartir a través de

Biblioteca cliente de Azure AI Projects para JavaScript: versión 1.0.0-beta.8

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.
  • Obtenga un cliente de Azure AI Inference para las finalizaciones de chat, las incrustaciones de texto o imágenes mediante las .inference operaciones.
  • Lea un archivo o cadena Prompty y represente mensajes para clientes de inferencia, mediante la PromptTemplate clase.
  • Ejecute evaluaciones para evaluar el rendimiento de las aplicaciones de IA generativa, utilizando las evaluations 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

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:

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());

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.0-beta.8/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.

Obtener un ChatCompletionsClient autenticado

El proyecto de Azure AI Foundry puede tener uno o varios modelos de IA implementados que admitan la finalización de chats. Pueden ser modelos de OpenAI, modelos de Microsoft o modelos de otros proveedores. Use el código siguiente para obtener un cliente autenticado del paquete azure-ai-inference y ejecutar una llamada de finalización de chat.

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".

const client = project.inference.chatCompletions();
const response = await client.post({
  body: {
    model: deploymentName,
    messages: [{ role: "user", content: "How many feet are in a mile?" }],
  },
});
console.log(response.body.choices[0].message.content);

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);

Evaluación

La evaluación de la biblioteca cliente de Azure AI Project está diseñada para evaluar el rendimiento de las aplicaciones de IA generativa en la nube. El resultado de la aplicación de IA generativa se mide cuantitativamente con métricas basadas en matemáticas, métricas de calidad y seguridad asistidas por IA. Las métricas se definen como evaluadores. Los evaluadores integrados o personalizados pueden proporcionar información completa sobre las capacidades y limitaciones de la aplicación.

Evaluador

Los evaluadores son clases o funciones personalizadas o predefinidas que están diseñadas para medir la calidad de los resultados de los modelos de lenguaje o las aplicaciones de IA generativa.

Los evaluadores están disponibles a través del SDK azure-ai-evaluation para la experiencia local y también en la biblioteca de evaluadores de Azure AI Foundry para usarlos en la nube.

Puede encontrar más detalles sobre los evaluadores integrados y personalizados aquí.

Ejecutar evaluación en la nube

Para ejecutar la evaluación en la nube, se necesita lo siguiente:

  • Evaluadores
  • Datos a evaluar
  • [Opcional] Modelo de Azure Open AI.
Evaluadores

Para ejecutar el evaluador en la nube, se necesita el evaluador ID . Para obtenerlo a través de código, use azure-ai-evaluation

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

const dataset: DatasetVersion = await project.datasets.uploadFile(
  "jss-eval-sample-dataset",
  "1",
  "./samples_folder/sample_data_evaluation.jsonl",
);
Datos a evaluar

La evaluación en la nube admite datos en forma de jsonl archivo. Los datos se pueden cargar a través del método upload_file auxiliar en el cliente del proyecto.

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

const dataset: DatasetVersion = await project.datasets.uploadFile(
  "jss-eval-sample-dataset",
  "1",
  "./samples_folder/sample_data_evaluation.jsonl",
);
[Opcional] Modelo de OpenAI de Azure

El proyecto de Azure AI Foundry incluye un punto de conexión predeterminado de Azure Open AI al que se puede acceder fácilmente mediante el siguiente código. Esto proporciona los detalles del punto de conexión de Azure OpenAI. Algunos de los evaluadores necesitan un modelo que admita la finalización del chat.

const defaultConnection = await project.connections.getDefault("AzureOpenAI");
Ejemplo: Evaluación remota
import { EvaluationWithOptionalName, EvaluatorIds, Evaluation } from "@azure/ai-projects";

const newEvaluation: EvaluationWithOptionalName = {
  displayName: "Evaluation 1",
  description: "This is a test evaluation",
  data: {
    type: "dataset",
    id: "data-id", // dataset.name
  },
  evaluators: {
    relevance: {
      id: EvaluatorIds.RELEVANCE,
      initParams: {
        deploymentName: "gpt-4o-mini",
      },
      dataMapping: {
        query: "${data.query}",
        response: "${data.response}",
      },
    },
  },
};
const evalResp = await project.evaluations.createRun(newEvaluation);
console.log("Create a new evaluation:", JSON.stringify(evalResp, null, 2));
// get the evaluation by ID
const eval2 = await project.evaluations.get(evalResp.name);
console.log("Get the evaluation by ID:", eval2);

const evaluations: Evaluation[] = [];
const evaluationNames: string[] = [];
for await (const evaluation of project.evaluations.list()) {
  evaluations.push(evaluation);
  evaluationNames.push(evaluation.displayName ?? "");
}
console.log("List of evaluation display names:", evaluationNames);

// This is temporary, as interface recommend the name of the evaluation
const name = evaluations[0].name;
const evaluation = await project.evaluations.get(name);
console.log("Get an evaluation by ID:", JSON.stringify(evaluation, null, 2));

NOTA: Para ejecutar evaluadores localmente, consulte Evaluar con el SDK de evaluación de Azure AI.

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'

Informes de 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.

Contribuyendo

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 abierto de conducta 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.