Azure AI Projects-klientbibliotek för JavaScript – version 1.0.1

2025-10-15

AI Projects-klientbiblioteket ger enkel åtkomst till resurser i ditt Azure AI Foundry-projekt. Använd portalen om du vill:

Skapa och kör agenter med hjälp av .agents egenskapen på klienten.
Hämta en AzureOpenAI-klient med hjälp av .inference.azureOpenAI metoden.
Räkna upp AI-modeller som distribueras till ditt Foundry-projekt med hjälp av åtgärderna .deployments .
Räkna upp anslutna Azure-resurser i ditt Foundry-projekt med hjälp av åtgärderna .connections .
Ladda upp dokument och skapa datauppsättningar för att referera till dem med hjälp av åtgärderna .datasets .
Skapa och räkna upp sökindex med hjälp av åtgärderna .indexes .
Aktivera OpenTelemetry-spårning med hjälp av enable_telemetry funktionen.

Produktdokumentation | Prover | Paket (npm) | Referensdokumentation för | APIKällkod för SDK

Innehållsförteckning

Komma igång
Viktiga begrepp
- Skapa och autentisera klienten
Exempel
Felsökning
- undantag
- Rapporteringsproblem
Nästa steg
bidra med

Komma igång

Förutsättning

Auktorisering

Entra-ID krävs för att autentisera klienten. Programmet behöver ett objekt som implementerar TokenCredential--gränssnittet. Kodexempel här använder StandardAzureCredential. För att få det att fungera behöver du:
- Rollen Contributor. Rolltilldelad kan utföras via fliken "Åtkomstkontroll (IAM)" i azure AI-projektresursen i Azure-portalen. Läs mer om rolltilldelningar här.
- Azure CLI- installerat.
- Du är inloggad på ditt Azure-konto genom att köra az login.
- Observera att om du har flera Azure-prenumerationer måste den prenumeration som innehåller din Azure AI Project-resurs vara din standardprenumeration. Kör az account list --output table för att visa en lista över alla prenumerationer och se vilken som är standard. Kör az account set --subscription "Your Subscription ID or Name" för att ändra din standardprenumeration.

Installera paketet

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

Viktiga begrepp

Skapa och autentisera klienten

För att konstruera en kan , kan hämtas AIProjectsClient från endpoint. Nedan antar vi att miljövariabeln AZURE_AI_PROJECT_ENDPOINT_STRING har definierats för att innehålla det här värdet:

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

Klienten använder API-version v1, se API-dokumentationen för att lära dig mer om de funktioner som stöds.

Exempel

Utföra agentåtgärder

Egenskapen .agents på ger AIProjectClient dig tillgång till en autentiserad AgentsClient från azure-ai-agents paketet. Nedan visar vi hur du skapar en agent och tar bort den. Om du vill se vad du kan göra med det agent du skapade kan du se de många exempel som azure-ai-agents är associerade med paketet.

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

Hämta en autentiserad AzureOpenAI-klient

Ditt Azure AI Foundry-projekt kan ha en eller flera OpenAI-modeller distribuerade som stöder chattslutföranden. Använd koden nedan för att hämta en autentiserad AzureOpenAI från openai-paketet och köra ett chattslutförandeanrop.

Kör koden nedan. Här antar vi att deploymentName (str) är definierat. Det är distributionsnamnet för en AI-modell i ditt Foundry-projekt. Som du ser på fliken "Modeller + slutpunkter" under kolumnen "Namn".

Uppdatera värdet api_version med ett som finns på raden "Dataplan – slutsatsledning" i den här tabellen.

Du har också alternativet (visas inte) för att uttryckligen ange Azure OpenAI-anslutningsnamnet i ditt AI Foundry-projekt, som inference.azureOpenAI metoden använder för att hämta inferensslutpunkten och autentiseringsuppgifterna. Om den inte finns används standardanslutningen 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));

Se mappen "slutsatsledning" i paketexemplen för ytterligare exempel.

Åtgärder för distributioner

Koden nedan visar några distributionsåtgärder som gör att du kan räkna upp de AI-modeller som distribueras till dina AI Foundry Projects. Dessa modeller kan visas på fliken "Modeller + slutpunkter" i ditt AI Foundry-projekt. Fullständiga exempel finns under mappen "distribution" i paketexemplen.

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

Åtgärder för anslutningar

Koden nedan visar några anslutningsåtgärder som gör att du kan räkna upp de Azure-resurser som är anslutna till dina AI Foundry Projects. Dessa anslutningar kan ses i "Hanteringscenter" på fliken "Anslutna resurser" i ditt AI Foundry-projekt. Fullständiga exempel finns under mappen "anslutningar" i paketexempel.

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

Åtgärder för datauppsättning

Koden nedan visar några Dataset-åtgärder. Fullständiga exempel finns under mappen "datasets" i paketexemplen.

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

Indexerar åtgärder

Koden nedan visar några indexåtgärder. Fullständiga exempel finns under mappen "index" i paketexemplen.

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

Felsökning

Exceptions

Klientmetoder som gör tjänstanrop skapar en RestError- för ett HTTP-statuskodsvar som inte lyckas från tjänsten. Undantagets code innehåller HTTP-svarsstatuskoden. Undantagets error.message innehåller ett detaljerat meddelande som kan vara till hjälp vid diagnostisering av problemet:

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

När du till exempel anger fel autentiseringsuppgifter:

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

Rapporteringsproblem

Om du vill rapportera problem med klientbiblioteket eller begära ytterligare funktioner öppnar du ett GitHub-problem här

Nästa steg

Ta en titt på paketexempel mapp som innehåller helt körbar kod.

Bidrag

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns i https://cla.microsoft.com.

När du skickar en pull-begäran avgör en CLA-robot automatiskt om du behöver tillhandahålla ett CLA och dekorera PR på rätt sätt (t.ex. etikett, kommentar). Följ bara anvisningarna från roboten. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet har antagit Microsoft Open Source Code of Conduct (Microsofts regler för uppförande för öppen källkod). Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Feedback

Var den här sidan till hjälp?