Sdílet prostřednictvím

Klientská knihovna Azure AI Projects pro JavaScript – verze 1.0.0-beta.2

  • Článek

Pomocí klientské knihovny AI Projects (ve verzi Preview) můžete:

  • vytvoření výčtu připojení v projektu Azure AI Foundry a získání vlastností připojení. Získejte například adresu URL koncového bodu odvozování a přihlašovací údaje přidružené k vašemu připojení Azure OpenAI.
  • vývoj agentů pomocí služby Azure AI Agent Service, využití rozsáhlého ekosystému modelů, nástrojů a možností od openAI, Microsoftu a dalších poskytovatelů LLM. Služba agenta Azure AI umožňuje vytváření agentů pro širokou škálu případů použití generující umělé inteligence. Balíček je aktuálně ve verzi Private Preview.
  • povolit trasování OpenTelemetry.

dokumentace k produktu

Obsah

Začínáme

Předpoklad

  • LTS verze Node.js
  • Předplatné Azure.
  • Projekt v Azure AI Foundry.
  • Připojovací řetězec projektu. Najdete ho na stránce přehledu projektu Azure AI Foundry v části Podrobnosti projektu. Níže předpokládáme, že proměnná prostředí AZURE_AI_PROJECTS_CONNECTION_STRING byla definována pro uložení této hodnoty.
  • K ověření klienta je potřeba ID entra. 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.
    • 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é.

Instalace balíčku

npm install @azure/ai-projects

Klíčové koncepty

Vytvoření a ověření klienta

Metoda objektu pro vytváření tříd fromConnectionString slouží k vytvoření klienta. Vytvoření klienta:

import { AIProjectsClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

import "dotenv/config";  

const connectionString = process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<connectionString>";

const client = AIProjectsClient.fromConnectionString(
  connectionString,
  new DefaultAzureCredential(),
);

Příklady

Vytvoření výčtu připojení

Váš projekt Azure AI Foundry má centrum pro správu. Když ho zadáte, zobrazí se v projektu karta s názvem Připojené zdroje. Operace .connections na klientovi umožňují vytvořit výčet připojení a získat vlastnosti připojení. Mezi vlastnosti připojení patří adresa URL prostředku a přihlašovací údaje pro ověřování, mimo jiné.

Níže jsou uvedeny příklady kódu operací připojení. Úplné ukázky najdete ve složce "připojení" v [ukázkách balíčků][ukázky].

Získání vlastností všech připojení

Zobrazení seznamu vlastností všech připojení v projektu Azure AI Foundry:

const connections = await client.connections.listConnections();
for (const connection of connections) {
  console.log(connection);
}

Získání vlastností všech připojení určitého typu

Zobrazení seznamu vlastností připojení určitého typu (tady Azure OpenAI):

const connections = await client.connections.listConnections({ category: "AzureOpenAI" });
for (const connection of connections) {
  console.log(connection);
}

Získání vlastností připojení podle názvu připojení

Získání vlastností připojení připojení s názvem connectionName:

const connection = await client.connections.getConnection("connectionName");
console.log(connection);

Získání vlastností připojení pomocí přihlašovacích údajů pro ověření:

const connection = await client.connections.getConnectionWithSecrets("connectionName");
console.log(connection);

Agenti (Preview)

Agenti v klientské knihovně Azure AI Projects jsou navrženi tak, aby usnadnili různé interakce a operace v rámci vašich projektů AI. Slouží jako základní komponenty, které spravují a provádějí úlohy, a k dosažení konkrétních cílů využívají různé nástroje a prostředky. Následující kroky popisují typickou sekvenci pro interakci s agenty. Další ukázky agentů najdete ve složce agentů v části [ukázky balíčků][samples].

Agenti se aktivně vyvíjejí. Brzy bude k dispozici registrační formulář pro privátní verzi Preview.

Vytvoření agenta

Tady je příklad vytvoření agenta:

const agent = await client.agents.createAgent("gpt-4o", {
  name: "my-agent",
  instructions: "You are a helpful assistant",
});

Pokud chcete agentům povolit přístup k prostředkům nebo vlastním funkcím, potřebujete nástroje. Nástroje můžete předat createAgent prostřednictvím tools a toolResources argumentů.

K tomu můžete použít ToolSet:

const toolSet = new ToolSet();
toolSet.addFileSearchTool([vectorStore.id]);
toolSet.addCodeInterpreterTool([codeInterpreterFile.id]);

// Create agent with tool set
const agent = await client.agents.createAgent("gpt-4o", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: toolSet.toolDefinitions,
  toolResources: toolSet.toolResources,
});
console.log(`Created agent, agent ID: ${agent.id}`);

Abychom mohli prohledávat soubory agentem, musíme nejprve nahrát soubor, vytvořit vektorové úložiště a přidružit ho k úložišti vektorů. Tady je příklad:

const localFileStream = fs.createReadStream("sample_file_for_upload.txt");
const file = await client.agents.uploadFile(localFileStream, "assistants", {
  fileName: "sample_file_for_upload.txt",
});
console.log(`Uploaded file, ID: ${file.id}`);

const vectorStore = await client.agents.createVectorStore({
  fileIds: [file.id],
  name: "my_vector_store",
});
console.log(`Created vector store, ID: ${vectorStore.id}`);

const fileSearchTool = ToolUtility.createFileSearchTool([vectorStore.id]);

const agent = await client.agents.createAgent("gpt-4o", {
  name: "SDK Test Agent - Retrieval",
  instructions: "You are helpful agent that can help fetch data from files you know about.",
  tools: [fileSearchTool.definition],
  toolResources: fileSearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

Vytvoření agenta s interpretem kódu

Tady je příklad pro nahrání souboru a jeho použití pro interpret kódu agentem:

const fileStream = fs.createReadStream("nifty_500_quarterly_results.csv");
const fFile = await client.agents.uploadFile(fileStream, "assistants", {
  fileName: "nifty_500_quarterly_results.csv",
});
console.log(`Uploaded local file, file ID : ${file.id}`);

const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([file.id]);

// Notice that CodeInterpreter must be enabled in the agent creation, otherwise the agent will not be able to see the file attachment
const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [codeInterpreterTool.definition],
  toolResources: codeInterpreterTool.resources,
});
console.log(`Created agent, agent ID: ${agent.id}`);

Vytvoření agenta pomocí zemnění Bingu

Pokud chcete agentu povolit vyhledávání prostřednictvím rozhraní API Bingu pro vyhledávání, použijete ToolUtility.createConnectionTool() společně s připojením.

Tady je příklad:

const bingGroundingConnectionId = "<bingGroundingConnectionId>";
const bingTool = ToolUtility.createConnectionTool(connectionToolType.BingGrounding, [
  bingGroundingConnectionId,
]);

const agent = await client.agents.createAgent("gpt-4-0125-preview", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [bingTool.definition],
});
console.log(`Created agent, agent ID : ${agent.id}`);

Azure AI Search je podnikový vyhledávací systém pro vysoce výkonné aplikace. Integruje se se službou Azure OpenAI a Azure Machine Learning a nabízí pokročilé technologie vyhledávání, jako je vektorové vyhledávání a fulltextové vyhledávání. Ideální pro přehledy znalostní báze, zjišťování informací a automatizaci

Tady je příklad integrace služby Azure AI Search:

const cognitiveServicesConnectionName = "<cognitiveServicesConnectionName>";
const cognitiveServicesConnection = await client.connections.getConnection(
  cognitiveServicesConnectionName,
);
const azureAISearchTool = ToolUtility.createAzureAISearchTool(
  cognitiveServicesConnection.id,
  cognitiveServicesConnection.name,
);

// Create agent with the Azure AI search tool
const agent = await client.agents.createAgent("gpt-4-0125-preview", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [azureAISearchTool.definition],
  toolResources: azureAISearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

Vytvoření agenta s voláním funkce

Agenty můžete vylepšit definováním funkcí zpětného volání jako nástrojů funkcí. Lze je poskytnout pro createAgent prostřednictvím kombinace tools a toolResources. Pro createAgentjsou k dispozici pouze definice a popisy funkce bez implementací. Run nebo event handler of stream vyvolá stav requires_action na základě definic funkce. Váš kód musí zpracovat tento stav a volat příslušné funkce.

Tady je příklad:

class FunctionToolExecutor {
  private functionTools: { func: Function, definition: FunctionToolDefinition }[];

  constructor() {
    this.functionTools = [{
      func: this.getUserFavoriteCity,
      ...ToolUtility.createFunctionTool({
        name: "getUserFavoriteCity",
        description: "Gets the user's favorite city.",
        parameters: {}
      })
    }, {
      func: this.getCityNickname,
      ...ToolUtility.createFunctionTool({
        name: "getCityNickname",
        description: "Gets the nickname of a city, e.g. 'LA' for 'Los Angeles, CA'.",
        parameters: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. Seattle, Wa" } } }
      })
    }, {
      func: this.getWeather,
      ...ToolUtility.createFunctionTool({
        name: "getWeather",
        description: "Gets the weather for a location.",
        parameters: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. Seattle, Wa" }, unit: { type: "string", enum: ['c', 'f'] } } }
      })
    }];
  }

  private getUserFavoriteCity(): {} {
    return { "location": "Seattle, WA" };
  }

  private getCityNickname(location: string): {} {
    return { "nickname": "The Emerald City" };
  }

  private getWeather(location: string, unit: string): {} {
    return { "weather": unit === "f" ? "72f" : "22c" };
  }

  public invokeTool(toolCall: RequiredToolCallOutput & FunctionToolDefinitionOutput): ToolOutput | undefined {
    console.log(`Function tool call - ${toolCall.function.name}`);
    const args = [];
    if (toolCall.function.parameters) {
      try {
        const params = JSON.parse(toolCall.function.parameters);
        for (const key in params) {
          if (Object.prototype.hasOwnProperty.call(params, key)) {
            args.push(params[key]);
          }
        }
      } catch (error) {
        console.error(`Failed to parse parameters: ${toolCall.function.parameters}`, error);
        return undefined;
      }
    }
    const result = this.functionTools.find((tool) => tool.definition.function.name === toolCall.function.name)?.func(...args);
    return result ? {
      toolCallId: toolCall.id,
      output: JSON.stringify(result)
    } : undefined;
  }

  public getFunctionDefinitions(): FunctionToolDefinition[] {
    return this.functionTools.map(tool => {return tool.definition});
  }
}

const functionToolExecutor = new FunctionToolExecutor();
const functionTools = functionToolExecutor.getFunctionDefinitions();
const agent = await client.agents.createAgent("gpt-4o",
  {
    name: "my-agent",
    instructions: "You are a weather bot. Use the provided functions to help answer questions. Customize your responses to the user's preferences as much as possible and use friendly nicknames for cities whenever possible.",
    tools: functionTools
  });
console.log(`Created agent, agent ID: ${agent.id}`);

Vytvořit vlákno

Pro každou relaci nebo konverzaci se vyžaduje vlákno. Tady je příklad:

const thread = await client.agents.createThread();

Vytvoření vlákna s prostředkem nástroje

V některých scénářích může být potřeba přiřadit konkrétní prostředky jednotlivým vláknům. Chcete-li toho dosáhnout, zadáte argument toolResourcescreateThread. V následujícím příkladu vytvoříte vektorové úložiště a nahrajete soubor, povolíte agenta pro vyhledávání souborů pomocí argumentu tools a pak přidružíte soubor k vláknu pomocí argumentu toolResources.

const localFileStream = fs.createReadStream("sample_file_for_upload.txt");
const file = await client.agents.uploadFile(localFileStream, "assistants", {
  fileName: "sample_file_for_upload.txt",
});
console.log(`Uploaded file, ID: ${file.id}`);

const vectorStore = await client.agents.createVectorStore({
  fileIds: [file.id],
  name: "my_vector_store",
});
console.log(`Created vector store, ID: ${vectorStore.id}`);

const fileSearchTool = ToolUtility.createFileSearchTool([vectorStore.id]);

const agent = await client.agents.createAgent("gpt-4o", {
  name: "SDK Test Agent - Retrieval",
  instructions: "You are helpful agent that can help fetch data from files you know about.",
  tools: [fileSearchTool.definition],
});
console.log(`Created agent, agent ID : ${agent.id}`);

// Create thread with file resources.
// If the agent has multiple threads, only this thread can search this file.
const thread = await client.agents.createThread({ toolResources: fileSearchTool.resources });

Vytvořit zprávu

Pokud chcete vytvořit zprávu pro zpracování asistenta, předáte user jako role a otázku jako content:

const message = await client.agents.createMessage(thread.id, {
  role: "user",
  content: "hello, world!",
});

Vytvoření zprávy s přílohou hledání souborů

Pokud chcete připojit soubor ke zprávě pro vyhledávání obsahu, použijte ToolUtility.createFileSearchTool() a argument attachments:

const fileSearchTool = ToolUtility.createFileSearchTool();
const message = await client.agents.createMessage(thread.id, {
  role: "user",
  content: "What feature does Smart Eyewear offer?",
  attachments: {
    fileId: file.id,
    tools: [fileSearchTool.definition],
  },
});

Vytvoření zprávy s přílohou interpretu kódu

K připojení souboru ke zprávě pro analýzu dat použijete ToolUtility.createCodeInterpreterTool() a argument attachment.

Tady je příklad:

// notice that CodeInterpreter must be enabled in the agent creation,
// otherwise the agent will not be able to see the file attachment for code interpretation
const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();
const agent = await client.agents.createAgent("gpt-4-1106-preview", {
  name: "my-assistant",
  instructions: "You are helpful assistant",
  tools: [codeInterpreterTool.definition],
});
console.log(`Created agent, agent ID: ${agent.id}`);

const thread = client.agents.createThread();
console.log(`Created thread, thread ID: ${thread.id}`);

const message = await client.agents.createMessage(thread.id, {
  role: "user",
  content:
    "Could you please create bar chart in TRANSPORTATION sector for the operating profit from the uploaded csv file and provide file to me?",
  attachments: {
    fileId: file.id,
    tools: [codeInterpreterTool.definition],
  },
});
console.log(`Created message, message ID: ${message.id}`);

Vytvoření spuštění, Run_and_Process nebo streamu

Tady je příklad createRun a dotazování, dokud se spuštění nedokončuje:

let run = await client.agents.createRun(thread.id, agent.id);

// Poll the run as long as run status is queued or in progress
while (
  run.status === "queued" ||
  run.status === "in_progress" ||
  run.status === "requires_action"
) {
  // Wait for a second
  await new Promise((resolve) => setTimeout(resolve, 1000));
  run = await client.agents.getRun(thread.id, run.id);
}

K dotazování sady SDK vaším jménem použijte metodu createThreadAndRun.

Tady je příklad:

const run = await client.agents.createThreadAndRun(thread.id, agent.id);

U streamování se také nemusí brát v úvahu dotazování.

Tady je příklad:

const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

Zpracování událostí je možné provést následujícím způsobem:

for await (const eventMessage of streamEventMessages) {
switch (eventMessage.event) {
  case RunStreamEvent.ThreadRunCreated:
    console.log(`ThreadRun status: ${(eventMessage.data as ThreadRunOutput).status}`)
    break;
  case MessageStreamEvent.ThreadMessageDelta:
    {
      const messageDelta = eventMessage.data as MessageDeltaChunk;
      messageDelta.delta.content.forEach((contentPart) => {
        if (contentPart.type === "text") {
          const textContent = contentPart as MessageDeltaTextContent
          const textValue = textContent.text?.value || "No text"
          console.log(`Text delta received:: ${textValue}`)
        }
      });
    }
    break;

  case RunStreamEvent.ThreadRunCompleted:
    console.log("Thread Run Completed");
    break;
  case ErrorEvent.Error:
    console.log(`An error occurred. Data ${eventMessage.data}`);
    break;
  case DoneEvent.Done:
    console.log("Stream completed.");
    break;
  }
}

Načtení zprávy

Pokud chcete načíst zprávy z agentů, použijte následující příklad:

const messages = await client.agents.listMessages(thread.id);

// The messages are following in the reverse order,
// we will iterate them and output only text contents.
for (const dataPoint of messages.data.reverse()) {
    const lastMessageContent: MessageContentOutput = dataPoint.content[dataPoint.content.length - 1];
    console.log( lastMessageContent);
    if (isOutputOfType<MessageTextContentOutput>(lastMessageContent, "text")) {
      console.log(`${dataPoint.role}: ${(lastMessageContent as MessageTextContentOutput).text.value}`);
    }
  }

Načtení souboru

Soubory nahrané agenty nelze načíst zpět. Pokud váš případ použití potřebuje přístup k obsahu souboru nahranému agenty, doporučujeme zachovat další kopii přístupnou vaší aplikací. Soubory vygenerované agenty jsou však možné načíst pomocí getFileContent.

Tady je příklad načítání ID souborů ze zpráv:

const messages = await client.agents.listMessages(thread.id);
const imageFile = (messages.data[0].content[0] as MessageImageFileContentOutput).imageFile;
const imageFileName = (await client.agents.getFile(imageFile.fileId)).filename;

const fileContent = await (await client.agents.getFileContent(imageFile.fileId).asNodeStream()).body;
if (fileContent) {
  const chunks: Buffer[] = [];
  for await (const chunk of fileContent) {
    chunks.push(Buffer.from(chunk));
  }
  const buffer = Buffer.concat(chunks);
  fs.writeFileSync(imageFileName, buffer);
} else {
  console.error("Failed to retrieve file content: fileContent is undefined");
}
console.log(`Saved image file to: ${imageFileName}`);

Roztrhání

Pokud chcete prostředky po dokončení úkolů odebrat, použijte následující funkce:

await client.agents.deleteVectorStore(vectorStore.id);
console.log(`Deleted vector store, vector store ID: ${vectorStore.id}`);

await client.agents.deleteFile(file.id);
console.log(`Deleted file, file ID: ${file.id}`);

client.agents.deleteAgent(agent.id);
console.log(`Deleted agent, agent ID: ${agent.id}`);

Trasování

Do projektu Azure AI Foundry můžete přidat prostředek Azure Application Insights. Podívejte se na kartu Trasování ve vašem studiu. Pokud byl povolený, můžete získat připojovací řetězec Application Insights, nakonfigurovat agenty a sledovat úplnou cestu spuštění prostřednictvím služby Azure Monitor. Než vytvoříte agenta, můžete obvykle začít trasovat.

Instalace

Nezapomeňte nainstalovat OpenTelemetry a modul plug-in trasování sady Azure SDK prostřednictvím .

npm install @opentelemetry/api \
  @opentelemetry/instrumentation \
  @opentelemetry/sdk-trace-node \
  @azure/opentelemetry-instrumentation-azure-sdk \
  @azure/monitor-opentelemetry-exporter

Budete také potřebovat vývozce, který odešle telemetrii do back-endu pozorovatelnosti. Trasování můžete vytisknout do konzoly nebo použít místní prohlížeč, například řídicí panel Aspire.

Pokud se chcete připojit k řídicímu panelu Aspire nebo jinému back-endu kompatibilnímu s OpenTelemetry, nainstalujte vývozce OTLP:

npm install @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/exporter-metrics-otlp-proto

Příklad trasování

Tady je ukázka kódu, která se má zahrnout nad createAgent:

import { trace } from "@opentelemetry/api";
import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter"
import {
    ConsoleSpanExporter,
    NodeTracerProvider,
    SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-node";

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

const tracer = trace.getTracer("Agents Sample", "1.0.0");

const client = AIProjectsClient.fromConnectionString(
  connectionString || "", new DefaultAzureCredential()
);

if (!appInsightsConnectionString) {
  appInsightsConnectionString = await client.telemetry.getConnectionString();
}

if (appInsightsConnectionString) {
  const exporter = new AzureMonitorTraceExporter({
    connectionString: appInsightsConnectionString
  });
  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
}

await tracer.startActiveSpan("main", async (span) => {
    client.telemetry.updateSettings({enableContentRecording: true})
// ...

Ř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 { RestError } from "@azure/core-rest-pipeline"

// ...

try {
  const result = await client.connections.listConnections();
} catch (e as RestError) {
  console.log(`Status code: ${e.code}`);
  console.log(e.message);
}

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

Přispívající

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 v 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 přijal pravidla chování microsoftu 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.