Bagikan melalui

Pustaka klien Asisten OpenAI Azure untuk JavaScript - versi 1.0.0-beta.5

Pustaka klien Azure OpenAI Assistants untuk JavaScript adalah adaptasi REST API OpenAI yang menyediakan antarmuka idiomatik dan integrasi yang kaya dengan sisa ekosistem Azure SDK. Ini dapat terhubung ke sumber daya Azure OpenAI atau ke titik akhir inferensi OpenAI non-Azure, menjadikannya pilihan yang bagus untuk pengembangan OpenAI non-Azure sekalipun.

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Jika Anda ingin menggunakan sumber daya Azure OpenAI, Anda harus memiliki langganan Azure dan akses Azure OpenAI. Ini akan memungkinkan Anda membuat sumber daya Azure OpenAI dan mendapatkan URL koneksi serta kunci API. Untuk informasi selengkapnya, lihat Mulai Cepat: Mulai membuat teks menggunakan Azure OpenAI Service.

Jika Anda ingin menggunakan pustaka klien Azure OpenAI Assistants JS untuk menyambungkan ke OpenAI non-Azure, Anda memerlukan kunci API dari akun pengembang di https://platform.openai.com/.

Pasang paket @azure/openai-assistants

Instal pustaka klien Asisten OpenAI Azure untuk JavaScript dengan npm:

npm install @azure/openai-assistants

Membuat dan mengautentikasi AssistantsClient

Untuk mengonfigurasi klien untuk digunakan dengan Azure OpenAI, berikan URI titik akhir yang valid ke sumber daya Azure OpenAI bersama dengan kredensial kunci, kredensial token, atau kredensial identitas Azure yang sesuai yang berwenang untuk menggunakan sumber daya Azure OpenAI. Untuk mengonfigurasi klien agar terhubung ke layanan OpenAI, berikan kunci API dari portal pengembang OpenAI.

Menggunakan Kunci API dari Azure

Gunakan Portal Microsoft Azure untuk menelusuri sumber daya OpenAI Anda dan mengambil kunci API, atau gunakan cuplikan Azure CLI di bawah ini:

Catatan: Terkadang kunci API disebut sebagai "kunci langganan" atau "kunci API langganan."

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Konsep utama

Lihat dokumentasi "cara kerja asisten" OpenAI untuk gambaran umum konsep dan hubungan yang digunakan dengan asisten. Gambaran umum ini sangat mengikuti contoh gambaran umum OpenAI untuk menunjukkan dasar-dasar membuat, menjalankan, dan menggunakan asisten dan utas.

Untuk memulai, buat AssistantsClient:

const assistantsClient = new AssistantsClient("<endpoint>", new AzureKeyCredential("<azure_api_key>"));

Dengan klien, asisten kemudian dapat dibuat. asisten adalah antarmuka yang dibuat khusus untuk model OpenAI yang dapat memanggil Alat sambil memungkinkan instruksi tingkat tinggi sepanjang masa pakai asisten.

Kode untuk membuat asisten:

const assistant = await assistantsClient.createAssistant({
  model: "gpt-4-1106-preview",
  name: "JS Math Tutor",
  instructions: "You are a personal math tutor. Write and run code to answer math questions.",
  tools: [{ type: "code_interpreter" }]
});

Sesi percakapan antara Asisten dan pengguna disebut Utas. Utas menyimpan Pesan dan secara otomatis menangani pemotongan agar pas dengan konten ke dalam konteks model.

Untuk membuat utas:

const assistantThread = await assistantsClient.createThread();

Pesan mewakili pesan yang dibuat oleh Asisten atau pengguna. Pesan dapat menyertakan teks, gambar, dan file lainnya. Pesan disimpan sebagai daftar di Utas. Dengan utas yang dibuat, pesan dapat dibuat di dalamnya:

const question = "I need to solve the equation '3x + 11 = 14'. Can you help me?";
const messageResponse = await assistantsClient.createMessage(assistantThread.id, "user", question);

Eksekusi mewakili pemanggilan Asisten pada Utas. Asisten menggunakan konfigurasinya dan Pesan Utas untuk melakukan tugas dengan memanggil model dan alat. Sebagai bagian dari Eksekusi, Asisten menambahkan Pesan ke Utas. Eksekusi kemudian dapat dimulai yang mengevaluasi utas terhadap asisten:

let runResponse = await assistantsClient.createRun(assistantThread.id, {
   assistantId: assistant.id,
   instructions: "Please address the user as Jane Doe. The user has a premium account." 
});

Setelah eksekusi dimulai, eksekusi kemudian harus dijajaki sampai mencapai status terminal:

do {
  await new Promise((resolve) => setTimeout(resolve, 800));
  runResponse = await assistantsClient.getRun(assistantThread.id, runResponse.id);
} while (runResponse.status === "queued" || runResponse.status === "in_progress")

Dengan asumsi eksekusi berhasil diselesaikan, mencantumkan pesan dari utas yang dijalankan sekarang akan mencerminkan informasi baru yang ditambahkan oleh asisten:

const runMessages = await assistantsClient.listMessages(assistantThread.id);
for (const runMessageDatum of runMessages.data) {
  for (const item of runMessageDatum.content) {
    if (item.type === "text") {
      console.log(item.text.value);
    } else if (item.type === "image_file") {
      console.log(item.imageFile.fileId);
    }
  }
}

Contoh output dari urutan ini:

2023-11-14 20:21:23 -  assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).
2023-11-14 20:21:18 -       user: I need to solve the equation `3x + 11 = 14`. Can you help me?

Bekerja dengan file untuk pengambilan

File dapat diunggah lalu direferensikan oleh asisten atau pesan. Pertama, gunakan API pengunggahan umum dengan tujuan 'asisten' untuk membuat ID file tersedia:

const filename = "<path_to_text_file>";
await fs.writeFile(filename, "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.", "utf8");
const uint8array = await fs.readFile(filename);
const uploadAssistantFile = await assistantsClient.uploadFile(uint8array, "assistants", { filename });

Setelah diunggah, ID file kemudian dapat diberikan ke asisten saat dibuat. Perhatikan bahwa ID file hanya akan digunakan jika alat yang sesuai seperti Penerjemah Kode atau Pengambilan diaktifkan.

const fileAssistant = await assistantsClient.createAssistant({
  model: "gpt-4-1106-preview",
  name: "JS SDK Test Assistant - Retrieval",
  instructions: "You are a helpful assistant that can help fetch data from files you know about.",
  tools: [{ type: "retrieval" }],
  fileIds: [ uploadAssistantFile.id ]
});

Dengan asosiasi ID file dan alat yang didukung diaktifkan, asisten kemudian akan dapat menggunakan data terkait saat menjalankan utas.

Menggunakan alat fungsi dan panggilan fungsi paralel

Seperti yang dijelaskan dalam dokumentasi OpenAI untuk alat asisten, alat yang mereferensikan kemampuan yang ditentukan pemanggil sebagai fungsi dapat diberikan kepada asisten untuk memungkinkannya menyelesaikan dan memisahkan secara dinamis selama eksekusi.

Di sini, diuraikan adalah asisten sederhana yang "tahu caranya," melalui fungsi yang disediakan pemanggil:

  1. Mendapatkan kota favorit pengguna
  2. Mendapatkan nama panggilan untuk kota tertentu
  3. Dapatkan cuaca saat ini, secara opsional dengan unit suhu, di kota

Untuk melakukan ini, mulailah dengan menentukan fungsi yang akan digunakan -- implementasi aktual di sini hanyalah stub yang representatif.

// Example of a function that defines no parameters
const getFavoriteCity = () => "Atlanta, GA";
const getUserFavoriteCityTool = { 
  type: "function",
  function: {
    name: "getUserFavoriteCity",
    description: "Gets the user's favorite city.",
    parameters: {
      type: "object",
      properties: {}
    }
  }
}; 

// Example of a function with a single required parameter
const getCityNickname = (city) => { 
  switch (city) { 
    case "Atlanta, GA": 
      return "The ATL"; 
    case "Seattle, WA": 
      return "The Emerald City"; 
    case "Los Angeles, CA":
      return "LA"; 
    default: 
      return "Unknown"; 
  }
};

const getCityNicknameTool = { 
  type: "function",
  function: {
    name: "getCityNickname",
    description: "Gets the nickname for a city, e.g. 'LA' for 'Los Angeles, CA'.",
    parameters: { 
      type: "object",
      properties: { 
        city: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA"
        } 
      }
    }
  }
};

// Example of a function with one required and one optional, enum parameter
const getWeatherAtLocation = (location, temperatureUnit = "f") => {
  switch (location) { 
    case "Atlanta, GA": 
      return temperatureUnit === "f" ? "84f" : "26c"; 
    case "Seattle, WA": 
      return temperatureUnit === "f" ? "70f" : "21c"; 
    case "Los Angeles, CA":
      return temperatureUnit === "f" ? "90f" : "28c"; 
    default: 
      return "Unknown"; 
  }
};

const getWeatherAtLocationTool = { 
  type: "function",
  function: {
    name: "getWeatherAtLocation",
    description: "Gets the current weather at a provided location.",
    parameters: { 
      type: "object",
      properties: { 
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA"
        },
        temperatureUnit: {
          type: "string",
          enum: ["f", "c"],
        }
      },
      required: ["location"]
    }
  }
};

Dengan fungsi yang ditentukan dalam alat yang sesuai, asisten sekarang dapat dibuat yang mengaktifkan alat tersebut:

  const weatherAssistant = await assistantsClient.createAssistant({
  // note: parallel function calling is only supported with newer models like gpt-4-1106-preview
  model: "gpt-4-1106-preview",
  name: "JS SDK Test Assistant - Weather",
  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: [getUserFavoriteCityTool, getCityNicknameTool, getWeatherAtLocationTool]
});

Jika alat panggilan asisten, kode panggilan harus menyelesaikan ToolCall instans menjadi instans yang ToolOutputSubmission cocok. Untuk kenyamanan, contoh dasar diekstrak di sini:

const getResolvedToolOutput = (toolCall) => {
  const toolOutput = { toolCallId: toolCall.id };

  if (toolCall["function"]) {
    const functionCall = toolCall["function"];
    const functionName = functionCall.name;
    const functionArgs = JSON.parse(functionCall["arguments"] ?? {});

    switch (functionName) {
      case "getUserFavoriteCity":
        toolOutput.output = getFavoriteCity();
        break;
      case "getCityNickname":
        toolOutput.output = getCityNickname(functionArgs["city"]);
        break;
      case "getWeatherAtLocation":
        toolOutput.output = getWeatherAtLocation(functionArgs.location, functionArgs.temperatureUnit);
        break;
      default:
        toolOutput.output = `Unknown function: ${functionName}`;
        break;
    }
  }
  return toolOutput;
};

Untuk menangani input pengguna seperti "seperti apa cuaca saat ini di kota favorit saya?", polling respons untuk penyelesaian harus dilengkapi dengan RunStatus pemeriksaan untuk RequiresAction atau, dalam hal ini, keberadaan RequiredAction properti saat dijalankan. Kemudian, pengumpulan ToolOutputSubmissions harus dikirimkan ke eksekusi melalui SubmitRunToolOutputs metode sehingga eksekusi dapat dilanjutkan:

const question = "What's the weather like right now in my favorite city?";
let runResponse = await assistantsClient.createThreadAndRun({ 
  assistantId: weatherAssistant.id, 
  thread: { messages: [{ role: "user", content: question }] },
  tools: [getUserFavoriteCityTool, getCityNicknameTool, getWeatherAtLocationTool]
});

do {
  await new Promise((resolve) => setTimeout(resolve, 500));
  runResponse = await assistantsClient.getRun(runResponse.threadId, runResponse.id);
  
  if (runResponse.status === "requires_action" && runResponse.requiredAction.type === "submit_tool_outputs") {
    const toolOutputs = [];

    for (const toolCall of runResponse.requiredAction.submitToolOutputs.toolCalls) {
      toolOutputs.push(getResolvedToolOutput(toolCall));
    }
    runResponse = await assistantsClient.submitToolOutputsToRun(runResponse.threadId, runResponse.id, toolOutputs);
  }
} while (runResponse.status === "queued" || runResponse.status === "in_progress")

Perhatikan bahwa, saat menggunakan model yang didukung, asisten mungkin meminta agar beberapa fungsi dipanggil secara paralel. Model yang lebih lama hanya dapat memanggil satu fungsi pada satu waktu.

Setelah semua panggilan fungsi yang diperlukan diselesaikan, eksekusi akan dilanjutkan secara normal dan pesan yang telah selesai pada utas akan berisi output model yang dilengkapi dengan output alat fungsi yang disediakan.

Pemecahan Masalah

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

  • Last updated on