Libreria client di Progetti di intelligenza artificiale di Azure per JavaScript - versione 1.0.1

La libreria client di AI Projects offre un facile accesso alle risorse nel progetto Azure AI Foundry. Usarlo per:

Creare ed eseguire agenti utilizzando la .agents proprietà nel client.
Ottenere un client AzureOpenAI usando il .inference.azureOpenAI metodo.
Enumera i modelli di intelligenza artificiale distribuiti nel tuo progetto di fonderia utilizzando le .deployments operazioni.
Enumerare le risorse di Azure connesse nel progetto Foundry usando le .connections operazioni.
Carica documenti e crea set di dati per farvi riferimento utilizzando le .datasets operazioni.
Creare ed enumerare gli indici di ricerca utilizzando le .indexes operazioni.
Abilitare la traccia OpenTelemetry usando la enable_telemetry funzione.

Documentazione del | prodottoCampioni | Pacchetto (npm) | Documentazione | Codice sorgente SDK

Sommario

Introduzione
Concetti principali
- Creare ed autenticare il client
Examples
Risoluzione dei problemi
- Eccezioni
- La segnalazione dei problemi
Passaggi successivi
contributi

Come iniziare

Prerequisito

Autorizzazione

L'ID Entra è necessario per autenticare il client. L'applicazione necessita di un oggetto che implementa l'interfaccia token
. Gli esempi di codice qui usano DefaultAzureCredential. Per ottenere questo lavoro, è necessario:
- Ruolo Contributor. Il ruolo assegnato può essere eseguito tramite la scheda "Controllo di accesso (IAM)" della risorsa progetto di Intelligenza artificiale di Azure nel portale di Azure. Scopri di più sulle assegnazioni di ruolo qui.
- installato dell'interfaccia della riga di comando di Azure.
- Si è connessi all'account Azure eseguendo az login.
- Si noti che se si dispone di più sottoscrizioni di Azure, la sottoscrizione che contiene la risorsa del progetto di intelligenza artificiale di Azure deve essere la sottoscrizione predefinita. Eseguire az account list --output table per elencare tutte le sottoscrizioni e vedere quale è l'impostazione predefinita. Eseguire az account set --subscription "Your Subscription ID or Name" per modificare la sottoscrizione predefinita.

Installare il pacchetto

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

Concetti chiave

Creare ed autenticare il client

Per costruire un AIProjectsClient, può endpoint essere recuperato dal punto finale. Di seguito assumeremo che la variabile AZURE_AI_PROJECT_ENDPOINT_STRING d'ambiente sia stata definita per mantenere questo valore:

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

Il client utilizza la versione v1API , fare riferimento alla documentazione dell'API per ulteriori informazioni sulle funzionalità supportate.

Esempi

Esecuzione di operazioni dell'agente

La .agents proprietà sul AIProjectClient ti dà accesso a un autenticato AgentsClient dal azure-ai-agents pacchetto. Di seguito mostriamo come creare un agente ed eliminarlo. Per vedere cosa è possibile fare con il agent pacchetto creato, vedere i numerosi esempi associati al azure-ai-agents pacchetto.

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

Ottenere un client AzureOpenAI autenticato

Il progetto Azure AI Foundry può avere uno o più modelli OpenAI distribuiti che supportano il completamento delle chat. Usare il codice seguente per ottenere un AzureOpenAI autenticato dal pacchetto openai ed eseguire una chiamata di completamento della chat.

Esegui il codice seguente. Qui assumiamo che deploymentName (str) sia definito. È il nome di distribuzione di un modello di intelligenza artificiale nel progetto di fonderia. Come mostrato nella scheda "Modelli + endpoint", nella colonna "Nome".

Aggiorna il api_version valore con quello trovato nella riga "Piano dati - inferenza" in questa tabella.

È anche possibile specificare in modo esplicito il nome della connessione Azure OpenAI nel progetto AI Foundry, che il inference.azureOpenAI metodo userà per ottenere l'endpoint di inferenza e le credenziali di autenticazione. Se non è presente, verrà utilizzata la connessione Azure OpenAI predefinita.

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

Per altri esempi, vedere la cartella "inference" negli esempi di pacchetto .

Operazioni di distribuzione

Il codice seguente mostra alcune operazioni di distribuzione, che consentono di enumerare i modelli di intelligenza artificiale distribuiti nei progetti di fonderia di intelligenza artificiale. Questi modelli possono essere visualizzati nella scheda "Modelli + endpoint" nel tuo progetto AI Foundry. Gli esempi completi sono disponibili nella cartella "deployment" negli esempi di pacchetto.

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

Operazioni di connessione

Il codice seguente illustra alcune operazioni di connessione, che consentono di enumerare le risorse di Azure connesse ai progetti di fonderia di intelligenza artificiale. Queste connessioni possono essere visualizzate nel "Centro Gestione", nella scheda "Risorse connesse" del progetto AI Foundry. Gli esempi completi sono disponibili nella cartella "connections" negli esempi di pacchetto.

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

Operazioni sui set di dati

Il codice seguente mostra alcune operazioni del set di dati. Gli esempi completi sono disponibili nella cartella "datasets" negli esempi di pacchetto.

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

Operazioni sugli indici

Il codice seguente mostra alcune operazioni sugli indici. Gli esempi completi sono disponibili nella cartella "indexes" negli esempi di pacchetto.

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

Risoluzione dei problemi

Eccezioni

I metodi client che effettuano chiamate al servizio generano un RestError per una risposta di codice di stato HTTP non riuscita dal servizio. Il code dell'eccezione conterrà il codice di stato della risposta HTTP. L'error.message dell'eccezione contiene un messaggio dettagliato che può essere utile per diagnosticare il 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);
  }
}

Ad esempio, quando si specificano credenziali errate:

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

Segnalazione di problemi

Per segnalare problemi con la libreria client o richiedere funzionalità aggiuntive, aprire un problema di GitHub qui

Passaggi successivi

Esaminare la cartella degli esempi di pacchetti contenente codice completamente eseguibile.

Contribuire

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per informazioni dettagliate, visitare https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato il codice di comportamento open source Microsoft. Per altre informazioni, vedere domande frequenti sul codice di condotta o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-15