JavaScript için Azure OpenAI Yardımcıları istemci kitaplığı - sürüm 1.0.0-beta.5

JavaScript için Azure OpenAI Assistants istemci kitaplığı, OpenAI'nin REST API'lerinin, Azure SDK ekosisteminin geri kalanıyla idiomatic bir arabirim ve zengin tümleştirme sağlayan bir uyarlamadır. Azure OpenAI kaynaklarına veya Azure dışı OpenAI çıkarım uç noktasına bağlanarak Azure dışı OpenAI geliştirmesi için bile harika bir seçimdir.

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Node.jsLTS sürümleri
Safari, Chrome, Edge ve Firefox'un en son sürümleri.

Önkoşullar

Bir Azure OpenAI kaynağı kullanmak istiyorsanız azure aboneliğiniz ve Azure OpenAI erişiminiz olmalıdır. Bu, bir Azure OpenAI kaynağı oluşturmanıza ve hem bağlantı URL'sini hem de API anahtarlarını almanıza olanak sağlar. Daha fazla bilgi için bkz . Hızlı Başlangıç: Azure OpenAI Hizmeti'ni kullanarak metin oluşturmaya başlama.

Azure OpenAI dışı bir sunucuya bağlanmak için Azure OpenAI Assistants JS istemci kitaplığını kullanmak isterseniz adresinden bir geliştirici hesabından https://platform.openai.com/API anahtarına ihtiyacınız olacaktır.

`@azure/openai-assistants` paketini yükleyin

ile npmJavaScript için Azure OpenAI Assistants istemci kitaplığını yükleyin:

npm install @azure/openai-assistants

Oluşturma ve kimlik doğrulaması `AssistantsClient`

Bir istemciyi Azure OpenAI ile kullanılacak şekilde yapılandırmak için, Azure OpenAI kaynağına geçerli bir uç nokta URI'si ve Azure OpenAI kaynağını kullanma yetkisi olan ilgili anahtar kimlik bilgileri, belirteç kimlik bilgileri veya Azure kimlik bilgileri sağlayın. Bunun yerine istemciyi OpenAI'nin hizmetine bağlanacak şekilde yapılandırmak için OpenAI'nin geliştirici portalından bir API anahtarı sağlayın.

Azure'dan API Anahtarı Kullanma

OpenAI kaynağınıza göz atmak ve bir API anahtarı almak için Azure Portal'ı kullanın veya aşağıdaki Azure CLI parçacığını kullanın:

Not: Bazen API anahtarına "abonelik anahtarı" veya "abonelik API anahtarı" denir.

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

Önemli kavramlar

Yardımcılarla kullanılan kavramlara ve ilişkilere genel bakış için OpenAI'nin "yardımcıların çalışma şekli" belgelerine bakın. Bu genel bakış, yardımcıları ve iş parçacıklarını oluşturma, çalıştırma ve kullanma ile ilgili temel bilgileri göstermek için OpenAI'nin genel bakış örneğini yakından izler.

Başlamak için bir AssistantsClientoluşturun:

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

bir istemci ile bir yardımcı oluşturulabilir. yardımcı, Yardımcı ömrü boyunca üst düzey yönergelere izin verirken Araçları çağırabilen OpenAI modellerine yönelik amaca yönelik oluşturulmuş bir arabirimdir.

yardımcı oluşturma kodu:

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

Bir Yardımcı ile kullanıcı arasındaki konuşma oturumuna İş Parçacığı adı verilir. İş parçacıkları İletileri depolar ve içeriği modelin bağlamlarına sığdırmak için kesmeyi otomatik olarak işler.

İş parçacığı oluşturmak için:

const assistantThread = await assistantsClient.createThread();

İleti, Bir Yardımcı veya kullanıcı tarafından oluşturulan bir iletiyi temsil eden bir iletidir. İletiler metin, resim ve diğer dosyaları içerebilir. İletiler, İş Parçacığında liste olarak depolanır. Bir iş parçacığı oluşturulduğunda, üzerinde iletiler oluşturulabilir:

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

Çalıştırma, bir İş Parçacığındaki Bir Yardımcının çağrısını temsil eden bir durum. Yardımcı, modelleri ve araçları çağırarak görevleri gerçekleştirmek için bu yapılandırmayı ve İş Parçacığının İletilerini kullanır. Bir Çalıştırmanın parçası olarak, Yardımcı İletileri İş Parçacığına ekler. Ardından iş parçacığını bir yardımcı karşı değerlendiren bir çalıştırma başlatılabilir:

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

Çalıştırma başladıktan sonra terminal durumuna ulaşana kadar yoklanması gerekir:

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

Çalıştırmanın başarıyla tamamlandığı varsayıldığında, iş parçacığından çalıştırılan iletileri listelemek artık yardımcı tarafından eklenen yeni bilgileri yansıtacaktır:

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

Bu diziden örnek çıktı:

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?

Alma için dosyalarla çalışma

Dosyalar karşıya yüklenebilir ve ardından yardımcılar veya iletiler tarafından başvurulabilir. İlk olarak, dosya kimliğini kullanılabilir hale getirmek için 'yardımcılar' amacıyla genelleştirilmiş karşıya yükleme API'sini kullanın:

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

Karşıya yüklendikten sonra, dosya kimliği oluşturulduktan sonra bir yardımcı sağlanabilir. Dosya kimliklerinin yalnızca Kod Yorumlayıcı veya Alma gibi uygun bir araç etkinleştirildiğinde kullanılacağını unutmayın.

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

Dosya kimliği ilişkilendirmesi ve desteklenen bir araç etkinleştirildiğinde, yardımcı iş parçacıklarını çalıştırırken ilişkili verileri kullanabilir.

İşlev araçlarını ve paralel işlev çağrılarını kullanma

OpenAI'nin yardımcı araçlarına yönelik belgelerinde açıklandığı gibi, işlev olarak çağıran tanımlı özelliklere başvuran araçlar bir yardımcı bir çalıştırma sırasında dinamik olarak çözümlenmesine ve kesinleştirmesine olanak sağlamak için sağlanabilir.

Burada, arayan tarafından sağlanan işlevler aracılığıyla "nasıl yapılacağını bilen" basit bir yardımcı özetlenmiştir:

Kullanıcının en sevdiği şehri alma
Belirli bir şehir için takma ad alma
Bir şehirde isteğe bağlı olarak bir sıcaklık birimiyle geçerli hava durumunu alma

Bunu yapmak için kullanılacak işlevleri tanımlayarak başlayın. Buradaki gerçek uygulamalar yalnızca temsili saplamalardır.

// 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"]
    }
  }
};

Uygun araçlarında tanımlanan işlevlerle artık bu araçların etkinleştirildiği bir yardımcı oluşturulabilir:

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

yardımcı araçları çağırırsa, çağıran kodun örnekleri eşleşen ToolOutputSubmission örneklere çözümlemesi ToolCall gerekir. Kolaylık sağlamak için burada temel bir örnek ayıklanır:

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

"Şu anda favori şehrimde hava durumu nasıl?" gibi bir kullanıcı girişini işlemek için, tamamlanma yanıtının yoklanması, veya bu durumda özelliğin RequiredAction çalıştırılan varlığı için RequiresAction bir RunStatus denetimle desteklenmelidir. Ardından, komutunun koleksiyonu ToolOutputSubmissions , çalıştırmanın devam edebilmesi için yöntemi aracılığıyla SubmitRunToolOutputs çalıştırmaya gönderilmelidir:

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

Desteklenen modelleri kullanırken, yardımcı birkaç işlevin paralel olarak çağrılması istenebilir. Eski modeller aynı anda yalnızca bir işlevi çağırabilir.

Gerekli tüm işlev çağrıları çözümlendikten sonra çalıştırma normal şekilde devam eder ve iş parçacığındaki tamamlanmış iletiler, sağlanan işlev aracı çıkışlarıyla ekli model çıktısı içerir.

Sorun giderme

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2024-03-02