Bibliothèque cliente Azure AI Projects pour JavaScript - version 1.0.1

La bibliothèque cliente AI Projects permet d’accéder facilement aux ressources de votre projet Azure AI Foundry. Utilisez-le pour :

Créez et exécutez des agents à l’aide de la .agents propriété sur le client.
Obtenez un client AzureOpenAI à l’aide de cette .inference.azureOpenAI méthode.
Énumérez les modèles d’IA déployés dans votre projet de fonderie à l’aide des .deployments opérations.
Énumérez les ressources Azure connectées dans votre projet Foundry à l’aide des .connections opérations.
Téléchargez des documents et créez des jeux de données pour les référencer à l’aide des .datasets opérations.
Créez et énumérez des index de recherche à l’aide des .indexes opérations.
Activez le suivi OpenTelemetry à l’aide de la enable_telemetry fonction.

Documentation | du produitÉchantillons | Paquet (npm) | Documentation de référence sur l’API | Code source du SDK

Table des matières

Premiers pas
Concepts clés
- créer et authentifier le client
Exemples
résolution des problèmes
- Exceptions
- Les problèmes de création de rapports
Étapes suivantes
contribution

Mise en route

Prérequis

Autorisation

L’Entra ID est nécessaire pour authentifier le client. Votre application a besoin d’un objet qui implémente l’interface TokenCredential. Les exemples de code ici utilisent DefaultAzureCredential. Pour travailler, vous aurez besoin des éléments suivants :
- Rôle Contributor. Le rôle attribué peut être effectué via l’onglet « Contrôle d’accès (IAM) » de votre ressource Azure AI Project dans le portail Azure. Pour en savoir plus sur l’attribution des rôles , cliquez ici.
- azure CLI installé.
- Vous êtes connecté à votre compte Azure en exécutant az login.
- Notez que si vous avez plusieurs abonnements Azure, l’abonnement qui contient votre ressource Azure AI Project doit être votre abonnement par défaut. Exécutez az account list --output table pour répertorier l’ensemble de votre abonnement et voir lequel est la valeur par défaut. Exécutez az account set --subscription "Your Subscription ID or Name" pour modifier votre abonnement par défaut.

Installer le package

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

Concepts clés

Créer et authentifier le client

Pour construire un AIProjectsClient, le endpoint peut être récupéré à partir du point de terminaison. Ci-dessous, nous supposerons que la variable AZURE_AI_PROJECT_ENDPOINT_STRING d’environnement a été définie pour contenir cette valeur :

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

Le client utilise la version de v1l’API, reportez-vous à la documentation de l’API pour en savoir plus sur les fonctionnalités prises en charge.

Exemples

Exécution d’opérations de l’Agent

La .agents propriété sur le AIProjectClient vous donne accès à un authentifié AgentsClient à partir du azure-ai-agents package. Ci-dessous, nous montrons comment créer un agent et le supprimer. Pour voir ce que vous pouvez faire avec le agent que vous avez créé, consultez les nombreux exemples associés au azure-ai-agents package.

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

Obtenir un client AzureOpenAI authentifié

Votre projet Azure AI Foundry peut avoir un ou plusieurs modèles OpenAI déployés qui prennent en charge l’achèvement des conversations. Utilisez le code ci-dessous pour obtenir un AzureOpenAI authentifié à partir du package openai et exécuter un appel de complétion de conversation.

Exécutez le code ci-dessous. Ici, nous supposons que deploymentName (str) est défini. Il s’agit du nom de déploiement d’un modèle d’IA dans votre projet Foundry. Comme indiqué dans l’onglet « Modèles + points de terminaison », sous la colonne « Nom ».

Mettez à jour la api_version valeur avec celle qui se trouve dans la ligne « Plan de données - inférence » de cette table.

Vous avez également la possibilité (non illustrée) de spécifier explicitement le nom de la connexion Azure OpenAI dans votre projet AI Foundry, que la inference.azureOpenAI méthode utilisera pour obtenir le point de terminaison d’inférence et les informations d’identification d’authentification. S’il n’est pas présent, la connexion Azure OpenAI par défaut sera utilisée.

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

Pour obtenir des exemples supplémentaires, reportez-vous au dossier « inference » dans les exemples de package .

Opérations de déploiements

Le code ci-dessous montre certaines opérations de déploiement, qui vous permettent d’énumérer les modèles d’IA déployés dans vos projets AI Foundry. Ces modèles peuvent être consultés dans l’onglet « Modèles + points de terminaison » de votre projet AI Foundry. Les exemples complets se trouvent dans le dossier « deployment » des exemples de packages.

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

Opérations de connexions

Le code ci-dessous montre quelques opérations de connexion, qui vous permettent d’énumérer les ressources Azure connectées à vos projets AI Foundry. Ces connexions sont visibles dans le « Centre de gestion », dans l’onglet « Ressources connectées » de votre projet de fonderie d’IA. Vous trouverez des exemples complets sous le dossier « connexions » dans les exemples de package.

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

Opérations sur les ensembles de données

Le code ci-dessous montre certaines opérations de jeu de données. Les échantillons complets se trouvent dans le dossier « datasets » dans les exemples de package.

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

Opérations d’indexation

Le code ci-dessous montre quelques opérations d’index. Les échantillons complets se trouvent dans le dossier « indexes » dans les exemples de packages.

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

Résolution des problèmes

Exceptions

Les méthodes clientes qui effectuent des appels de service déclenchent une RestError pour une réponse de code d’état HTTP non réussie du service. La code de l’exception contiendra le code d’état de la réponse HTTP. Le error.message de l’exception contient un message détaillé qui peut être utile pour diagnostiquer le problème :

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

Par exemple, lorsque vous fournissez des informations d’identification incorrectes :

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

Signaler des problèmes

Pour signaler des problèmes avec la bibliothèque cliente ou demander des fonctionnalités supplémentaires, ouvrez un problème GitHub ici

Étapes suivantes

Examinez le dossier d’exemples de package contenant du code entièrement exécutable.

Contribuer

Ce projet accueille les contributions et suggestions. La plupart des contributions vous obligent à accepter un contrat de licence contributeur (CLA) déclarant que vous avez le droit, et en fait, de nous accorder les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Lorsque vous envoyez une demande de tirage( pull request), un bot CLA détermine automatiquement si vous devez fournir un CLA et décorer correctement la demande de tirage (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source Microsoft. Pour plus d’informations, consultez la FAQ sur le code de conduite ou contactez opencode@microsoft.com avec toutes les questions ou commentaires supplémentaires.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-15