Freigeben über

Azure AI Projects-Clientbibliothek für JavaScript – Version 1.0.1

Die AI Projects-Clientbibliothek bietet einfachen Zugriff auf Ressourcen in Ihrem Azure AI Foundry-Projekt. Verwenden Sie es zu folgenden Zwecken:

  • Erstellen und führen Sie Agents mithilfe der .agents Eigenschaft auf dem Client aus.
  • Rufen Sie mit der Methode .inference.azureOpenAI.
  • Listen Sie KI-Modelle auf, die in Ihrem Foundry-Projekt mithilfe der .deployments Vorgänge bereitgestellt wurden.
  • Listen Sie verbundene Azure-Ressourcen in Ihrem Foundry-Projekt mithilfe der .connections Vorgänge auf.
  • Laden Sie Dokumente hoch und erstellen Sie Datensätze, um sie mithilfe der .datasets Vorgänge zu referenzieren.
  • Erstellen und Auflisten von Suchindizes mithilfe der .indexes Vorgänge.
  • Aktivieren Sie die OpenTelemetry-Ablaufverfolgung mithilfe der enable_telemetry Funktion.

Produktdokumentation | Proben | Paket (npm) | API-Referenzdokumentation | SDK-Quellcode

Inhaltsverzeichnis

Erste Schritte

Voraussetzung

Autorisierung

  • Die Entra ID wird benötigt, um den Client zu authentifizieren. Ihre Anwendung benötigt ein Objekt, das die TokenCredential Schnittstelle implementiert. Codebeispiele verwenden hier DefaultAzureCredential. Um dies zu erreichen, benötigen Sie Folgendes:
    • Die rolle Contributor. Die zugewiesene Rolle kann über die Registerkarte "Access Control (IAM)" Ihrer Azure AI-Projektressource im Azure-Portal erfolgen. Weitere Informationen zu Rollenzuweisungen finden Sie hier.
    • Azure CLI installiert.
    • Sie sind bei Ihrem Azure-Konto angemeldet, indem Sie az loginausführen.
    • Beachten Sie, dass das Abonnement, das Ihre Azure AI Project-Ressource enthält, Ihr Standardabonnement sein muss, wenn Sie über mehrere Azure-Abonnements verfügen. Führen Sie az account list --output table aus, um ihr gesamtes Abonnement auflisten und zu sehen, welche Standardeinstellung ist. Führen Sie az account set --subscription "Your Subscription ID or Name" aus, um Ihr Standardabonnement zu ändern.

Installiere das Paket

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

Wichtige Begriffe

Erstellen und Authentifizieren des Clients

Um ein AIProjectsClientzu erstellen, kann das endpoint vom Endpunkt abgerufen werden. Im Folgenden gehen wir davon aus, dass die Umgebungsvariable AZURE_AI_PROJECT_ENDPOINT_STRING so definiert wurde, dass sie diesen Wert enthält:

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

Der Client verwendet die API-Version v1. Weitere Informationen zu den unterstützten Funktionen finden Sie in der API-Dokumentation .

Beispiele

Ausführen von Agentenvorgängen

Die .agents Eigenschaft auf der AIProjectClient gibt Ihnen Zugriff auf ein authentifiziertes AgentsClient aus dem azure-ai-agents Paket. Im Folgenden zeigen wir, wie Sie einen Agenten erstellen und löschen. Informationen dazu, was Sie mit dem von Ihnen agent erstellten Paket tun können, finden Sie in den vielen Beispielen , die dem azure-ai-agents Paket zugeordnet sind.

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

Abrufen eines authentifizierten AzureOpenAI-Clients

In Ihrem Azure AI Foundry-Projekt sind möglicherweise ein oder mehrere OpenAI-Modelle bereitgestellt, die Chatvervollständigungen unterstützen. Verwenden Sie den folgenden Code, um ein authentifiziertes AzureOpenAI aus dem openai-Paket abzurufen und einen Chatvervollständigungsaufruf auszuführen.

Führen Sie den folgenden Code aus. Hier gehen wir davon aus, dass deploymentName (str) definiert ist. Es handelt sich um den Bereitstellungsnamen eines KI-Modells in Ihrem Foundry-Projekt. Wie auf der Registerkarte "Modelle + Endpunkte" in der Spalte "Name" gezeigt.

Aktualisieren Sie den api_version Wert mit dem Wert in der Zeile "Datenebene - Inferenz" in dieser Tabelle.

Sie haben auch die Option (nicht gezeigt), den Azure OpenAI-Verbindungsnamen in Ihrem AI Foundry-Projekt explizit anzugeben, den die inference.azureOpenAI Methode zum Abrufen des Rückschlussendpunkts und der Authentifizierungsanmeldeinformationen verwendet. Wenn nicht vorhanden, wird die standardmäßige Azure OpenAI-Verbindung verwendet.

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

Weitere Beispiele finden Sie im Ordner "inference" in den Paketbeispielen .

Vorgänge für Bereitstellungen

Der folgende Code zeigt einige Bereitstellungsvorgänge, mit denen Sie die KI-Modelle auflisten können, die in Ihren AI Foundry-Projekten bereitgestellt werden. Diese Modelle sind auf der Registerkarte "Modelle + Endpunkte" in Ihrem AI Foundry-Projekt zu sehen. Vollständige Beispiele finden Sie im Ordner "deployment" in den Paketbeispielen.

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

Vorgänge "Verbindungen"

Der folgende Code zeigt einige Verbindungsvorgänge, mit denen Sie die Azure-Ressourcen auflisten können, die mit Ihren AI Foundry-Projekten verbunden sind. Diese Verbindungen sind im "Management Center", auf der Registerkarte "Verbundene Ressourcen" in Ihrem AI Foundry Projekt zu sehen. Vollständige Beispiele finden Sie unter dem Ordner "Connections" in den Paketbeispielen.

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

Vorgänge mit Datasets

Der folgende Code zeigt einige Dataset-Vorgänge. Vollständige Beispiele finden Sie im Ordner "datasets" in den Paketbeispielen.

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

Operationen bei Indizes

Der folgende Code zeigt einige Indexes-Vorgänge. Vollständige Beispiele finden Sie im Ordner "indexes" in den Paketbeispielen.

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

Problembehandlung

Ausnahmen

Clientmethoden, die Dienstaufrufe ausführen, lösen eine RestError- für eine nicht erfolgreiche HTTP-Statuscodeantwort des Diensts aus. Die code der Ausnahme enthält den HTTP-Antwortstatuscode. Die error.message der Ausnahme enthält eine detaillierte Meldung, die bei der Diagnose des Problems hilfreich sein kann:

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

Wenn Sie beispielsweise falsche Anmeldeinformationen angeben:

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

Melden von Problemen

Um Probleme mit der Clientbibliothek zu melden oder zusätzliche Features anzufordern, öffnen Sie bitte ein GitHub-Problem hier

Nächste Schritte

Sehen Sie sich die Paketbeispiele Ordners an, die vollständig ausgeführten Code enthalten.

Mitarbeit

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einem Mitwirkenden-Lizenzvertrag (CLA) zustimmen, der erklärt, dass Sie das Recht haben, uns tatsächlich die Rechte zur Nutzung Ihres Beitrags zu gewähren. Weitere Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie eine Pullanfrage einreichen, bestimmt ein CLA-Bot automatisch, ob Sie eine CLA bereitstellen und die PR entsprechend dekorieren müssen (z. B. Bezeichnung, Kommentar). Folgen Sie einfach den Anweisungen des Bots. Sie müssen dies nur einmal über alle Reposs hinweg tun, indem Sie unsereN CLA verwenden.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie im Code of Conduct FAQ oder wenden Sie sich an opencode@microsoft.com mit weiteren Fragen oder Kommentaren.

  • Last updated on