Pustaka klien Azure AI Projects untuk JavaScript - versi 1.0.1

Pustaka klien Proyek AI menyediakan akses mudah ke sumber daya di proyek Azure AI Foundry Anda. Gunakan untuk:

Buat dan jalankan Agen menggunakan .agents properti pada klien.
Dapatkan klien AzureOpenAI menggunakan metode ini .inference.azureOpenAI .
Sebutkan Model AI yang disebarkan ke Proyek Pengecoran Anda menggunakan .deployments operasi.
Hitung sumber daya Azure yang terhubung dalam proyek Foundry Anda menggunakan .connections operasi.
Unggah dokumen dan buat Himpunan Data untuk mereferensikannya menggunakan .datasets operasi.
Membuat dan menghitung Indeks Pencarian menggunakan .indexes operasi.
Aktifkan pelacakan OpenTelemetry menggunakan fungsi ini enable_telemetry .

Dokumentasi | produkSampel | Paket (npm) | Dokumentasi | referensi APIKode sumber SDK

Daftar isi

Panduan Memulai
Konsep Utama
- Membuat dan mengautentikasi klien
Examples
Pemecahan masalah
- Pengecualian
- masalah Pelaporan
Langkah berikutnya
Berkontribusi

Memulai Langkah Pertama

Prasyarat

Otorisasi

Entra ID diperlukan untuk mengautentikasi klien. Aplikasi Anda memerlukan objek yang mengimplementasikan antarmuka TokenCredential
. Sampel kode di sini menggunakan DefaultAzureCredential. Untuk mendapatkan pekerjaan itu, Anda akan membutuhkan:
- Peran Contributor. Peran yang ditetapkan dapat dilakukan melalui tab "Kontrol Akses (IAM)" sumber daya Proyek Azure AI Anda di portal Microsoft Azure. Pelajari lebih lanjut tentang penetapan peran di sini.
- Azure CLI terinstal.
- Anda masuk ke akun Azure Anda dengan menjalankan az login.
- Perhatikan bahwa jika Anda memiliki beberapa langganan Azure, langganan yang berisi sumber daya Proyek Azure AI Anda harus menjadi langganan default Anda. Jalankan az account list --output table untuk mencantumkan semua langganan Anda dan melihat langganan mana yang merupakan default. Jalankan az account set --subscription "Your Subscription ID or Name" untuk mengubah langganan default Anda.

Pasang paketnya

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

Konsep utama

Membuat dan mengautentikasi klien

Untuk membuat AIProjectsClient, dapat endpoint diambil dari titik akhir. Di bawah ini kita akan mengasumsikan variabel AZURE_AI_PROJECT_ENDPOINT_STRING lingkungan didefinisikan untuk menyimpan nilai ini:

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

Klien menggunakan versi v1API , lihat dokumentasi API untuk mempelajari lebih lanjut tentang fitur yang didukung.

Contoh

Melakukan operasi Agen

.agents Properti di memberi AIProjectClient Anda akses ke yang diautentikasi AgentsClient dari azure-ai-agents paket. Di bawah ini kami menunjukkan cara membuat agen dan menghapusnya. Untuk melihat apa yang dapat Anda lakukan dengan yang agent Anda buat, lihat banyak sampel yang terkait dengan azure-ai-agents paket.

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

Dapatkan klien AzureOpenAI yang diautentikasi

Proyek Azure AI Foundry Anda mungkin memiliki satu atau beberapa model OpenAI yang disebarkan yang mendukung penyelesaian obrolan. Gunakan kode di bawah ini untuk mendapatkan AzureOpenAI yang diautentikasi dari paket openai , dan jalankan panggilan penyelesaian obrolan.

Jalankan kode di bawah ini. Di sini kita berasumsi deploymentName (str) didefinisikan. Ini adalah nama penyebaran model AI di Foundry Project Anda. Seperti yang ditunjukkan di tab "Model + titik akhir", di bawah kolom "Nama".

Perbarui api_version nilai dengan nilai yang ditemukan di baris "Bidang data - inferensi" dalam tabel ini.

Anda juga memiliki opsi (tidak ditampilkan) untuk secara eksplisit menentukan nama koneksi Azure OpenAI di AI Foundry Project Anda, yang inference.azureOpenAI akan digunakan metode untuk mendapatkan titik akhir inferensi dan kredensial autentikasi. Jika tidak ada, koneksi Azure OpenAI default akan digunakan.

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

Lihat folder "inferensi" dalam sampel paket untuk sampel tambahan.

Operasi penyebaran

Kode di bawah ini menunjukkan beberapa operasi Penyebaran, yang memungkinkan Anda menghitung model AI yang disebarkan ke Proyek AI Foundry Anda. Model-model ini dapat dilihat di tab "Model + titik akhir" di Proyek AI Foundry Anda. Sampel lengkap dapat ditemukan di bawah folder "penyebaran" di sampel paket.

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

Operasi koneksi

Kode di bawah ini menunjukkan beberapa operasi Koneksi, yang memungkinkan Anda menghitung Sumber Daya Azure yang terhubung ke Proyek AI Foundry Anda. Koneksi ini dapat dilihat di "Pusat Manajemen", di tab "Sumber daya yang terhubung" di Proyek AI Foundry Anda. Sampel lengkap dapat ditemukan di bawah folder "koneksi" dalam sampel paket.

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

Operasi himpunan data

Kode di bawah ini menunjukkan beberapa operasi Himpunan Data. Sampel lengkap dapat ditemukan di bawah folder "himpunan data" dalam sampel paket.

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

Operasi indeks

Kode di bawah ini menunjukkan beberapa operasi Indeks. Sampel lengkap dapat ditemukan di bawah folder "indeks" di sampel paket.

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

Penyelesaian Masalah

Pengecualian

Metode klien yang melakukan panggilan layanan meningkatkan RestError untuk respons kode status HTTP yang tidak berhasil dari layanan. code pengecualian akan menyimpan kode status respons HTTP. error.message pengecualian berisi pesan terperinci yang mungkin berguna dalam mendiagnosis masalah:

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

Misalnya, saat Anda memberikan kredensial yang salah:

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

Melaporkan masalah

Untuk melaporkan masalah dengan pustaka klien, atau meminta fitur tambahan, buka masalah GitHub di sini

Langkah selanjutnya

Lihat folder sampel paket , yang berisi kode yang dapat dijalankan sepenuhnya.

Berpartisipasi

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Saat Anda mengirimkan permintaan pull, cla-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik atau hubungi opencode@microsoft.com dengan pertanyaan atau komentar tambahan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-15