Biblioteca de clientes do Azure AI Projects para JavaScript – versão 1.0.1

A biblioteca de clientes do AI Projects fornece acesso fácil aos recursos em seu projeto do Azure AI Foundry. Use-o para:

Crie e execute Agentes usando a .agents propriedade no cliente.
Obtenha um cliente AzureOpenAI usando o .inference.azureOpenAI método.
Enumere os modelos de IA implantados em seu projeto de fundição usando as .deployments operações.
Enumere os recursos conectados do Azure em seu projeto do Foundry usando as .connections operações.
Carregue documentos e crie conjuntos de dados para referenciá-los usando as .datasets operações.
Crie e enumere índices de pesquisa usando as .indexes operações.
Habilite o rastreamento do OpenTelemetry usando a enable_telemetry função.

Documentação do | produtoAmostras | Pacote (npm) | Documentação | Código-fonte do SDK

Sumário

Introdução
Principais conceitos
- Criar e autenticar o cliente
Exemplos
Solução de problemas
- Exceções
- problemas de relatório
Próximas Etapas
contribuindo com

Como começar

Pré-requisito

Autorização

O ID do Entra é necessário para autenticar o cliente. Seu aplicativo precisa de um objeto que implemente a interface
TokenCredential. Exemplos de código aqui usam DefaultAzureCredential. Para que isso funcione, você precisará de:
- A função Contributor. A função atribuída pode ser feita por meio da guia "Controle de Acesso (IAM)" do recurso do Projeto de IA do Azure no portal do Azure. Saiba mais sobre atribuições de função aqui.
- CLI do Azure instalada.
- Você está conectado à sua conta do Azure executando az login.
- Observe que, se você tiver várias assinaturas do Azure, a assinatura que contém o recurso do Projeto de IA do Azure deverá ser sua assinatura padrão. Execute az account list --output table para listar toda a sua assinatura e ver qual é o padrão. Execute az account set --subscription "Your Subscription ID or Name" para alterar sua assinatura padrão.

Instalar o pacote

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

Conceitos principais

Criar e autenticar o cliente

Para construir um AIProjectsClient, o endpoint pode ser buscado no ponto de extremidade. Abaixo, vamos supor que a variável AZURE_AI_PROJECT_ENDPOINT_STRING de ambiente foi definida para manter esse valor:

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

O cliente usa a versão v1da API, consulte a documentação da API para saber mais sobre os recursos suportados.

Exemplos

Executando operações do Agente

A .agents propriedade no AIProjectClient dá acesso a um autenticado AgentsClient do azure-ai-agents pacote. Abaixo, mostramos como criar um agente e excluí-lo. Para ver o que você pode fazer com o agent que você criou, consulte os muitos exemplos associados ao azure-ai-agents pacote.

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

Obter um cliente AzureOpenAI autenticado

Seu projeto do Azure AI Foundry pode ter um ou mais modelos OpenAI implantados que dão suporte a conclusões de chat. Use o código abaixo para obter um AzureOpenAI autenticado do pacote openai e execute uma chamada de conclusão de chat.

Execute o código abaixo. Aqui assumimos que deploymentName (str) está definido. É o nome de implantação de um modelo de IA em seu projeto do Foundry. Conforme mostrado na guia "Modelos + endpoints", na coluna "Nome".

Atualize o api_version valor com um encontrado na linha "Plano de dados - inferência" nesta tabela.

Você também tem a opção (não mostrada) de especificar explicitamente o nome da conexão OpenAI do Azure em seu Projeto AI Foundry, que o inference.azureOpenAI método usará para obter o ponto de extremidade de inferência e as credenciais de autenticação. Se não estiver presente, a conexão padrão do Azure OpenAI será usada.

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

Consulte a pasta "inferência" nos exemplos de pacote para obter exemplos adicionais.

Operações de implantações

O código abaixo mostra algumas operações de Implantações, que permitem enumerar os modelos de IA implantados em seus Projetos do AI Foundry. Esses modelos podem ser vistos na guia "Modelos + endpoints" em seu projeto AI Foundry. Exemplos completos podem ser encontrados na pasta "deployment" nos exemplos de pacote.

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

Operações de conexões

O código a seguir mostra algumas operações de conexão, que permitem enumerar os recursos do Azure conectados aos seus projetos do AI Foundry. Essas conexões podem ser vistas no "Centro de Gerenciamento", na guia "Recursos conectados" em seu projeto do AI Foundry. Exemplos completos podem ser encontrados na pasta "conexões" no exemplos de pacote.

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

Operações de conjunto de dados

O código abaixo mostra algumas operações do conjunto de dados. Exemplos completos podem ser encontrados na pasta "datasets" nos exemplos de pacotes.

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

Operações de índices

O código abaixo mostra algumas operações de índices. Exemplos completos podem ser encontrados na pasta "índices" no pacote de exemplos.

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

Resolução de problemas

Exceções

Os métodos de cliente que fazem chamadas de serviço geram uma restError para uma resposta de código de status HTTP sem êxito do serviço. O code da exceção conterá o código de status de resposta HTTP. O error.message da exceção contém uma mensagem detalhada que pode ser útil para diagnosticar o problema:

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

Por exemplo, quando você fornece credenciais erradas:

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

Problemas de relatórios

Para relatar problemas com a biblioteca de clientes ou solicitar recursos adicionais, abra um problema do GitHub aqui

Próximas etapas

Examine os exemplos de pacote pasta, contendo código totalmente executável.

Contribuindo

Este projeto recebe contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença de Colaborador) declarando que você tem o direito de, e realmente fazer, conceder-nos os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

Comentários

Esta página foi útil?

Last updated on 2025-10-15