Azure AI Projects-clientbibliotheek voor JavaScript - versie 1.0.1

2025-10-15

De clientbibliotheek van AI Projects biedt eenvoudige toegang tot resources in uw Azure AI Foundry-project. Gebruik deze voor het volgende:

Creëer en voer agenten uit met behulp van de .agents eigenschap op de client.
Verkrijg een AzureOpenAI-client met behulp van de .inference.azureOpenAI methode.
Sommen AI-modellen op die zijn geïmplementeerd in uw Foundry-project met behulp van de .deployments bewerkingen.
Som verbonden Azure-resources in uw Foundry-project op met behulp van de .connections bewerkingen.
Upload documenten en maak datasets om ernaar te verwijzen met behulp van de .datasets bewerkingen.
Maak en inventariseer zoekindexen met behulp van de .indexes bewerkingen.
Schakel OpenTelemetrie-tracering in met behulp van de enable_telemetry functie.

Product documentatie | Monsters | Pakket (npm) | Documentatie voor | API-referentieSDK-broncode

Inhoudsopgave

Aan de slag
belangrijke concepten
- de client maken en verifiëren
Voorbeelden
Problemen oplossen
- Uitzonderingen
- problemen melden
Volgende stappen
bijdragen

Aan de slag

Voorwaarde

Autorisatie

Entra ID is nodig om de client te authenticeren. Uw toepassing heeft een object nodig waarmee de interface TokenCredential wordt geïmplementeerd. Codevoorbeelden hier gebruiken DefaultAzureCredential-. Om dat te kunnen doen, hebt u het volgende nodig:
- De Contributor rol. De toegewezen rol kan worden uitgevoerd via het tabblad Toegangsbeheer (IAM) van uw Azure AI-projectresource in Azure Portal. Meer informatie over roltoewijzingen vindt u hier.
- Azure CLI geïnstalleerd.
- U bent aangemeld bij uw Azure-account door az loginuit te voeren.
- Houd er rekening mee dat als u meerdere Azure-abonnementen hebt, het abonnement dat uw Azure AI Project-resource bevat, uw standaardabonnement moet zijn. Voer az account list --output table uit om al uw abonnement weer te geven en te zien welke standaard is. Voer az account set --subscription "Your Subscription ID or Name" uit om uw standaardabonnement te wijzigen.

Installeer het pakket

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

Belangrijke concepten

De client maken en verifiëren

Om een AIProjectsClientte construeren, kan de worden opgehaald vanaf het endpointeindpunt. Hieronder gaan we ervan uit dat de omgevingsvariabele AZURE_AI_PROJECT_ENDPOINT_STRING is gedefinieerd om deze waarde vast te houden:

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

De client gebruikt de API-versie v1, raadpleeg de API-documentatie voor meer informatie over de ondersteunde functies.

Voorbeelden

Uitvoeren van agentbewerkingen

De .agents eigenschap aan de AIProjectClient geeft u toegang tot een geauthenticeerd AgentsClient uit het azure-ai-agents pakket. Hieronder laten we zien hoe u een agent aanmaakt en verwijdert. Als u wilt zien wat u kunt doen met het agent pakket dat u hebt gemaakt, bekijkt u de vele voorbeelden die aan het azure-ai-agents pakket zijn gekoppeld.

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

Een geverifieerde AzureOpenAI-client ophalen

In uw Azure AI Foundry-project zijn mogelijk een of meer OpenAI-modellen geïmplementeerd die ondersteuning bieden voor het voltooien van chats. Gebruik de onderstaande code om een geverifieerde AzureOpenAI uit het openai-pakket te halen en een chataanroep uit te voeren.

Voer de onderstaande code uit. Hier gaan we ervan uit dat deploymentName (str) is gedefinieerd. Het is de implementatienaam van een AI-model in uw Foundry Project. Zoals weergegeven op het tabblad "Modellen + eindpunten", onder de kolom "Naam".

Werk de api_version waarde bij met een waarde die u vindt in de rij 'Gegevensvlak - deductie' in deze tabel.

U hebt ook de optie (niet weergegeven) om expliciet de Azure OpenAI-verbindingsnaam op te geven in uw AI Foundry-project, die de inference.azureOpenAI methode zal gebruiken om het deductie-eindpunt en de verificatiereferenties op te halen. Als dit niet het geval is, wordt de standaard Azure OpenAI-verbinding gebruikt.

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

Zie de map "inferentie" in de pakketvoorbeelden voor aanvullende voorbeelden.

Implementaties operaties

De onderstaande code toont enkele implementatiebewerkingen, waarmee u de AI-modellen kunt opsommen die zijn geïmplementeerd in uw AI Foundry-projecten. Deze modellen zijn te zien op het tabblad "Modellen + eindpunten" in uw AI Foundry-project. Volledige voorbeelden zijn te vinden onder de map "deployment" in de pakketvoorbeelden.

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

Verbindingen bewerkingen

De onderstaande code toont enkele verbindingsbewerkingen, waarmee u de Azure-resources kunt opsommen die zijn verbonden met uw AI Foundry-projecten. Deze verbindingen zijn te zien in het "Management Center", op het tabblad "Verbonden bronnen" in uw AI Foundry-project. Volledige voorbeelden vindt u in de map Verbindingen in de pakketvoorbeelden.

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

Bewerkingen van gegevenssets

De onderstaande code toont enkele bewerkingen van de gegevensset. Volledige voorbeelden zijn te vinden onder de map "datasets" in de pakketvoorbeelden.

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

Bewerkingen van indexen

De onderstaande code toont enkele indexbewerkingen. Volledige monsters zijn te vinden onder de map "indexen" in de pakketvoorbeelden.

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

Probleemoplossingsproces

Uitzonderingen

Clientmethoden waarmee serviceaanroepen worden uitgevoerd, genereren een RestError- voor een niet-geslaagd HTTP-statuscodeantwoord van de service. De code van de uitzondering bevat de HTTP-antwoordstatuscode. De error.message van de uitzondering bevat een gedetailleerd bericht dat nuttig kan zijn bij het diagnosticeren van het probleem:

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

Als u bijvoorbeeld onjuiste referenties opgeeft:

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

Problemen melden

Als u problemen met de clientbibliotheek wilt melden of aanvullende functies wilt aanvragen, opent u hier een GitHub-probleem

Volgende stappen

Bekijk de pakketvoorbeelden map met volledig uitvoerbare code.

Bijdragen

Dit project verwelkomt bijdragen en suggesties. Voor de meeste bijdragen moet u akkoord gaan met een Licentieovereenkomst voor inzenders (CLA) waarin wordt aangegeven dat u het recht hebt om, en daadwerkelijk, ons de rechten te verlenen om uw bijdrage te gebruiken. Ga naar https://cla.microsoft.comvoor meer informatie.

Wanneer u een pull-aanvraag indient, bepaalt een CLA-bot automatisch of u een CLA moet opgeven en de pull-aanvraag op de juiste wijze moet inrichten (bijvoorbeeld label, opmerking). Volg gewoon de instructies van de bot. U hoeft dit slechts eenmaal te doen voor alle opslagplaatsen met behulp van onze CLA.

Dit project onderschrijft de Microsoft Open Source gedragscode. Zie de veelgestelde vragen over gedragscodes voor meer informatie of neem contact op met opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Feedback

Is deze pagina nuttig?