Partilhar via

Biblioteca de cliente do Azure AI Projects para JavaScript - versão 1.0.1

A biblioteca de cliente AI Projects fornece acesso fácil a recursos em seu projeto do Azure AI Foundry. Utilize-o para:

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

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

Índice

Como Começar

Pré-requisito

Autorização

  • O Entra ID é necessário para autenticar o cliente. Seu aplicativo precisa de um objeto que implemente o TokenCredential interface. Os exemplos de código aqui usam DefaultAzureCredential. Para que isso funcione, você precisará de:
    • O Contributor papel. A função atribuída pode ser feita por meio da guia "Controle de Acesso (IAM)" do seu recurso do Projeto Azure AI no portal do Azure. Saiba mais sobre as 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 seu recurso do Azure AI Project deve ser sua assinatura padrão. Execute az account list --output table para listar todas as suas assinaturas e ver qual é a padrão. Execute az account set --subscription "Your Subscription ID or Name" para alterar sua assinatura padrão.

Instale o pacote

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

Conceitos-chave

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ão de bate-papo. 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 deploymentName que (str) está definido. É o nome de implantação de um modelo de IA em seu projeto de fundição. Como mostrado na guia "Modelos + pontos finais", 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 do Azure OpenAI em seu projeto do 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 amostras adicionais.

Operações de implantação

O código abaixo mostra algumas operações de implantações, que permitem enumerar os modelos de IA implantados em seus projetos de fundição de IA. Estes modelos podem ser vistos no separador "Modelos + endpoints" no seu AI Foundry Project. 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 abaixo mostra algumas operações de Conexão, que permitem enumerar os Recursos do Azure conectados aos seus Projetos de Fundição de IA. Essas conexões podem ser vistas no "Management Center", na guia "Recursos conectados" no seu AI Foundry Project. Amostras completas podem ser encontradas na pasta "conexões" no amostras 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 do conjunto de dados

O código abaixo mostra algumas operações de conjunto de dados. Amostras completas podem ser encontradas na pasta "conjuntos de dados" nas amostras de pacote.

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. Amostras completas podem ser encontradas na pasta "índices" nas amostras de pacote.

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

Solução de problemas

Exceções

Os métodos de cliente que fazem chamadas de serviço geram um RestError para uma resposta de código de status HTTP sem êxito do serviço. O code da exceção manterá o código de status da resposta HTTP. O error.message da exceção contém uma mensagem detalhada que pode ser útil no diagnóstico do 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'

Comunicar problemas

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

Próximos passos

Dê uma olhada nos exemplos de pacote pasta, contendo código totalmente executável.

Contribuir

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

Quando você envia uma solicitação pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar o 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 Open Source 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 quaisquer perguntas ou comentários adicionais.

  • Last updated on