Sdílet prostřednictvím

Klientská knihovna Azure AI Projects pro JavaScript – verze 1.0.1

Klientská knihovna AI Projects poskytuje snadný přístup k prostředkům ve vašem projektu Azure AI Foundry. Použijte ji k následujícím akcím:

  • Vytvořte a spusťte agenty.agents pomocí vlastnosti v klientovi.
  • Získejte klienta AzureOpenAI pomocí této .inference.azureOpenAI metody.
  • Pomocí těchto operací vytvořte výčet modelů AI nasazených do vašeho projektu .deployments Foundry.
  • Pomocí těchto operací vytvořte výčet připojených prostředků Azure v projektu .connections Foundry.
  • Nahrajte dokumenty a vytvořte datové sady , abyste na ně mohli odkazovat .datasets pomocí operací.
  • Pomocí těchto operací vytvořte a vytvořte výčet vyhledávacích indexů.indexes.
  • Povolte trasování OpenTelemetry pomocí enable_telemetry této funkce.

Dokumentace | k výrobkuVzorky | Balíček (npm) | Referenční dokumentace | k rozhraní APIZdrojový kód sady SDK

Obsah

Začínáme

Předpoklad

Autorizace

  • Entra ID je potřeba k ověření klienta. Vaše aplikace potřebuje objekt, který implementuje rozhraní TokenCredential. Ukázky kódu zde používají DefaultAzureCredential. Abyste mohli pracovat, budete potřebovat:
    • Role Contributor. Přiřazení role je možné provést prostřednictvím karty Řízení přístupu (IAM) vašeho prostředku projektu Azure AI na webu Azure Portal. Další informace o přiřazení rolí najdete tady.
    • nainstalované rozhraní příkazové ho řádku Azure CLI.
    • Jste přihlášeni ke svému účtu Azure spuštěním az login.
    • Upozorňujeme, že pokud máte více předplatných Azure, musí být výchozím předplatným předplatného, které obsahuje váš prostředek projektu Azure AI. Spuštěním az account list --output table zobrazte seznam všech vašich předplatných a podívejte se, která z nich je výchozí. Spuštěním az account set --subscription "Your Subscription ID or Name" změňte výchozí předplatné.

Nainstalujte balíček

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

Klíčové koncepty

Vytvoření a ověření klienta

Chcete-li vytvořit AIProjectsClient, lze je endpoint načíst z koncového bodu. Níže budeme předpokládat, že proměnná AZURE_AI_PROJECT_ENDPOINT_STRING prostředí byla definována tak, aby obsahovala tuto hodnotu:

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

Klient používá verzi v1rozhraní API, další informace o podporovaných funkcích naleznete v dokumentaci k rozhraní API .

Příklady

Provádění operací agenta

Vlastnost .agents na stránce poskytuje AIProjectClient přístup k ověřenému AgentsClient z azure-ai-agents balíčku. Níže si ukážeme, jak vytvořit agenta a odstranit jej. Pokud chcete zjistit, co můžete s vytvořenými agent soubory dělat, podívejte se na mnoho ukázek přidružených k azure-ai-agents balíčku.

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

Získání ověřeného klienta AzureOpenAI

Váš projekt Azure AI Foundry může mít nasazený jeden nebo více modelů OpenAI, které podporují dokončování chatu. Pomocí níže uvedeného kódu získejte ověřený AzureOpenAI z balíčku openai a spusťte volání dokončení chatu.

Spusťte níže uvedený kód. Zde předpokládáme, že deploymentName je definováno (str). Je to název nasazení modelu umělé inteligence ve vašem projektu Foundry. Jak je znázorněno na kartě "Modely + koncové body" ve sloupci "Název".

api_version Aktualizujte hodnotu hodnotou nalezenou v řádku "Rovina dat – odvození" v této tabulce.

Máte také možnost (není zobrazena) explicitně zadat název připojení Azure OpenAI ve vašem projektu AI Foundry, který metoda inference.azureOpenAI použije k získání koncového bodu odvození a přihlašovacích údajů pro ověřování. Pokud není k dispozici, použije se výchozí připojení 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));

Další ukázky najdete ve složce "inference" v ukázkách balíčků .

Operace nasazení

Následující kód ukazuje některé operace nasazení, které umožňují vytvořit výčet modelů AI nasazených do vašich projektů AI Foundry. Tyto modely lze vidět na kartě "Modely + koncové body" ve vašem projektu AI Foundry. Úplné ukázky najdete ve složce "deployment" v ukázkách balíčků.

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

Operace připojení

Následující kód ukazuje některé operace připojení, které umožňují vytvořit výčet prostředků Azure připojených k vašim projektům AI Foundry. Tato spojení lze vidět v "Centru správy", na kartě "Připojené zdroje" ve vašem projektu AI Foundry. Úplné ukázky najdete ve složce "připojení" v ukázkách balíčků .

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

Operace s datovými sadami

Následující kód ukazuje některé operace s datovou sadou. Úplné ukázky najdete ve složce "datasets" v ukázkách balíčků.

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

Indexuje operace

Následující kód ukazuje některé operace indexů. Úplné ukázky najdete ve složce "indexes" v ukázkách balíčků.

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

Řešení problémů

Výjimky

Klientské metody, které volání služby vyvolávají RestError pro odpověď stavového kódu HTTP bez úspěchu ze služby. code výjimky bude obsahovat stavový kód odpovědi HTTP. error.message výjimky obsahuje podrobnou zprávu, která může být užitečná při diagnostice problému:

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

Pokud například zadáte nesprávné přihlašovací údaje:

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

Hlášení problémů

Pokud chcete nahlásit problémy s klientskou knihovnou nebo požádat o další funkce, otevřete problém na GitHubu tady

Další kroky

Podívejte se na ukázky balíčků složce obsahující plně spustitelný kód.

Přispění

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která deklaruje, že máte právo a ve skutečnosti nám udělíte práva k používání vašeho příspěvku. Podrobnosti najdete na adrese https://cla.microsoft.com.

Když odešlete žádost o přijetí změn, robot CLA automaticky určí, jestli potřebujete poskytnout CLA, a odpovídajícím způsobem vyzdobit žádost o přijetí změn (např. popisek, komentář). Stačí postupovat podle pokynů poskytovaných robotem. Stačí to udělat jen jednou napříč všemi úložištěmi pomocí naší cla.

Tento projekt se řídí Pravidly chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k kodexu chování nebo se obraťte na opencode@microsoft.com s dalšími dotazy nebo komentáři.

  • Last updated on