適用於 JavaScript 的 Azure OpenAI 用戶端連結庫 - 1.0.0-beta.12 版

發行項
04/02/2024

適用於 JavaScript 的 Azure OpenAI 用戶端連結庫是 OpenAI REST API 的調整，可提供慣用的介面，並與 Azure SDK 生態系統的其餘部分進行豐富的整合。它可以連線到 Azure OpenAI 資源或非 Azure OpenAI 推斷端點，使其成為即使是非 Azure OpenAI 開發的絕佳選擇。

使用適用於 Azure OpenAI 的用戶端連結庫來：

Azure OpenAI 是一項受控服務，可讓開發人員從 Azure 資源上的 OpenAI 模型部署、調整和產生內容。

檢視下列範例：

多個完成
聊天機器人
摘要文字
使用聊天工具
產生影像
分析商務數據
轉譯和翻譯音訊檔案
使用 gpt-4-vision-preview 與影像聊天

重要連結：

開始使用

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

const client = new OpenAIClient(
  "https://<resource name>.openai.azure.com/", 
  new AzureKeyCredential("<Azure API key>")
);
const { id, created, choices, usage } = await client.getCompletions("<deployment ID>", ["YOUR PROMPT HERE"]);

目前支援的環境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

必要條件

如果您想要使用 Azure OpenAI 資源，您必須擁有 Azure 訂用帳戶和 Azure OpenAI 存取權。這可讓您建立 Azure OpenAI 資源，並同時取得連線 URL 和 API 金鑰。如需詳細資訊，請參閱快速入門：開始使用 Azure OpenAI 服務產生文字。

如果您想要使用 Azure OpenAI JS 用戶端連結庫來連線到非 Azure OpenAI，您需要來自開發人員帳戶的 https://platform.openai.com/API 密鑰。

安裝 `@azure/openai` 套件

使用 npm安裝適用於 JavaScript 的 Azure OpenAI 用戶端連結庫：

npm install @azure/openai

建立和驗證 `OpenAIClient`

若要設定用戶端以搭配 Azure OpenAI 使用，請提供有效的端點 URI 給 Azure OpenAI 資源，以及授權使用 Azure OpenAI 資源的對應密鑰認證、令牌認證或 Azure 身分識別認證。若要改為將用戶端設定為連線至 OpenAI 的服務，請從 OpenAI 的開發人員入口網站提供 API 金鑰。

從 Azure 使用 API 金鑰

使用 Azure 入口網站流覽至 OpenAI 資源並擷取 API 金鑰，或使用下列 Azure CLI 代碼段：

注意： 有時 API 金鑰稱為「訂用帳戶金鑰」或「訂用帳戶 API 金鑰」。

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

擁有 API 金鑰和端點之後，您可以使用 AzureKeyCredential 類別來驗證用戶端，如下所示：

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

const client = new OpenAIClient("<endpoint>", new AzureKeyCredential("<API key>"));

使用 Azure Active Directory 認證

用戶端 API 金鑰驗證用於大部分的範例中，但您也可以使用 Azure 身分識別連結庫向 Azure Active Directory 進行驗證。若要使用如下所示的 DefaultAzureCredential 提供者，或其他隨附於 Azure SDK 的認證提供者，請安裝 @azure/identity 套件：

npm install @azure/identity

您也需要註冊新的 AAD 應用程式，並將角色指派給您的服務主體，以授 "Cognitive Services User" 與 OpenAI 的存取權 (附注：其他角色，例如 "Owner" 不會授與必要的許可權，只會 "Cognitive Services User" 足以執行範例和範例程式代碼) 。

將 AAD 應用程式的用戶端識別碼、租使用者識別碼和客戶端密碼的值設定為環境變數：AZURE_CLIENT_ID、、。AZURE_TENANT_IDAZURE_CLIENT_SECRET

const { OpenAIClient } = require("@azure/openai");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new OpenAIClient("<endpoint>", new DefaultAzureCredential());

從 OpenAI 使用 API 金鑰

若要改為將用戶端設定為連線至 OpenAI 的服務，請從 OpenAI 的開發人員入口網站提供 API 金鑰。擁有 API 金鑰之後，您可以使用 OpenAIKeyCredential 類別來驗證用戶端，如下所示：

const { OpenAIClient, OpenAIKeyCredential } = require("@azure/openai");

const client = new OpenAIClient(new OpenAIKeyCredential("<API key>"));

重要概念

要瞭解的主要概念是完成。簡短說明，完成會以文字提示的形式提供其功能，該提示會使用特定模型，然後嘗試比對內容和模式，並提供輸出文字。下列代碼段提供粗略概觀：

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

async function main(){
  const client = new OpenAIClient(
  "https://your-azure-openai-resource.com/",
  new AzureKeyCredential("your-azure-openai-resource-api-key"));

  const { choices } = await client.getCompletions(
    "text-davinci-003", // assumes a matching model deployment or model name
    ["Hello, world!"]);

  for (const choice of choices) {
    console.log(choice.text);
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

範例

您可以使用範例熟悉不同的 API。

產生 Chatbot 回應

此範例會使用 DefaultAzureCredential 進行驗證，然後產生聊天回應以輸入聊天問題和訊息。

const { OpenAIClient } = require("@azure/openai");
const { DefaultAzureCredential } = require("@azure/identity");

async function main(){
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new OpenAIClient(endpoint, new DefaultAzureCredential());

  const deploymentId = "gpt-35-turbo";

  const messages = [
    { role: "system", content: "You are a helpful assistant. You will talk like a pirate." },
    { role: "user", content: "Can you help me?" },
    { role: "assistant", content: "Arrrr! Of course, me hearty! What can I do for ye?" },
    { role: "user", content: "What's the best way to train a parrot?" },
  ];

  console.log(`Messages: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.streamChatCompletions(deploymentId, messages, { maxTokens: 128 });
  for await (const event of events) {
    for (const choice of event.choices) {
      const delta = choice.delta?.content;
      if (delta !== undefined) {
        console.log(`Chatbot: ${delta}`);
      }
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

使用訂用帳戶金鑰產生多個完成

此範例會使用 Azure 訂用帳戶密鑰產生輸入提示的文字回應

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

async function main(){
  // Replace with your Azure OpenAI key
  const key = "YOUR_AZURE_OPENAI_KEY";
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new OpenAIClient(endpoint, new AzureKeyCredential(key));

  const examplePrompts = [
    "How are you today?",
    "What is Azure OpenAI?",
    "Why do children love dinosaurs?",
    "Generate a proof of Euler's identity",
    "Describe in single words only the good things that come into your mind about your mother.",
  ];

  const deploymentName = "text-davinci-003";

  let promptIndex = 0;
  const { choices } = await client.getCompletions(deploymentName, examplePrompts);
  for (const choice of choices) {
    const completion = choice.text;
    console.log(`Input: ${examplePrompts[promptIndex++]}`);
    console.log(`Chatbot: ${completion}`);
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

完成的摘要文字

這個範例會產生指定輸入提示的摘要。

const { OpenAIClient } = require("@azure/openai");
const { DefaultAzureCredential } = require("@azure/identity")

async function main(){
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new OpenAIClient(endpoint, new DefaultAzureCredential());

  const textToSummarize = `
    Two independent experiments reported their results this morning at CERN, Europe's high-energy physics laboratory near Geneva in Switzerland. Both show convincing evidence of a new boson particle weighing around 125 gigaelectronvolts, which so far fits predictions of the Higgs previously made by theoretical physicists.

    ""As a layman I would say: 'I think we have it'. Would you agree?"" Rolf-Dieter Heuer, CERN's director-general, asked the packed auditorium. The physicists assembled there burst into applause.
  :`;

  const summarizationPrompt = [`
    Summarize the following text.

    Text:
    """"""
    ${textToSummarize}
    """"""

    Summary:
  `];

  console.log(`Input: ${summarizationPrompt}`);

  const deploymentName = "text-davinci-003";

  const { choices } = await client.getCompletions(deploymentName, summarizationPrompt, {
    maxTokens: 64
  });
  const completion = choices[0].text;
  console.log(`Summarization: ${completion}`);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

使用聊天工具

工具藉由允許助理叫用已定義的函式和其他功能，以擴充聊天完成作業。若要使用聊天工具，請先定義函式工具：

const getCurrentWeather = {
    name: "get_current_weather",
    description: "Get the current weather in a given location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
        },
      },
      required: ["location"],
    },
  };

使用已定義的工具，在聊天完成要求的選項中包含該新定義：

const deploymentName = "gpt-35-turbo-1106";
const messages = [{ role: "user", content: "What is the weather like in Boston?" }];
const options = {
    tools: [
      {
        type: "function",
        function: getCurrentWeather,
      },
    ],
  };
const events = client.getChatCompletions(deploymentId, messages, options);

當助理決定應該使用一或多個工具時，回應訊息會包含一或多個「工具呼叫」，必須透過後續要求上的「工具訊息」來解析。這個工具對新要求訊息的呼叫解析可視為聊天完成的「回呼」類型。

// Purely for convenience and clarity, this function handles tool call responses.
function applyToolCall({ function: call, id }) {
    if (call.name === "get_current_weather") {
      const { location, unit } = JSON.parse(call.arguments);
      // In a real application, this would be a call to a weather API with location and unit parameters
      return {
        role: "tool",
        content: `The weather in ${location} is 72 degrees ${unit} and sunny.`,
        toolCallId: id,
      }
    }
    throw new Error(`Unknown tool call: ${call.name}`);
}

若要提供工具呼叫解析給助理，以允許繼續要求、提供所有先前的歷史內容，包括原始系統和使用者訊息、包含工具呼叫之助理的回應，以及解決每個工具的工具訊息-- 提出後續要求時。

const choice = result.choices[0];
const responseMessage = choice.message;
if (responseMessage?.role === "assistant") {
  const requestedToolCalls = responseMessage?.toolCalls;
  if (requestedToolCalls?.length) {
    const toolCallResolutionMessages = [
      ...messages,
      responseMessage,
      ...requestedToolCalls.map(applyToolCall),
    ];
    const result = await client.getChatCompletions(deploymentName, toolCallResolutionMessages);
    // continue handling the response as normal
  }
}

使用 DALL-E 映射產生模型產生影像

此範例會從指定的輸入提示產生批次映像。

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

async function main() {
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new OpenAIClient(endpoint, new AzureKeyCredential(azureApiKey));

  const deploymentName = "dalle-3";
  const prompt = "a monkey eating a banana";
  const size = "1024x1024";
  const n = 1;
  
  const results = await client.getImages(deploymentName, prompt, { n, size });

  for (const image of results.data) {
    console.log(`Image generation result URL: ${image.url}`);
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

分析商務數據

此範例會產生聊天回應，以輸入有關您商務數據的聊天問題。商務數據是透過 Azure 認知搜尋索引來提供。若要深入瞭解如何設定 Azure 認知搜尋索引作為數據源，請參閱快速入門：使用您自己的數據與 Azure OpenAI 模型聊天。

const { OpenAIClient } = require("@azure/openai");
const { DefaultAzureCredential } = require("@azure/identity");

async function main(){
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new OpenAIClient(endpoint, new DefaultAzureCredential());

  const deploymentId = "gpt-35-turbo";

  const messages = [
    { role: "user", content: "What's the most common customer feedback about our product?" },
  ];

  console.log(`Messages: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.streamChatCompletions(deploymentId, messages, { 
    maxTokens: 128,
    azureExtensionOptions: {
      extensions: [
        {
          type: "AzureCognitiveSearch",
          endpoint: "<Azure Cognitive Search endpoint>",
          key: "<Azure Cognitive Search admin key>",
          indexName: "<Azure Cognitive Search index name>",
        },
      ],
    },
  });
  for await (const event of events) {
    for (const choice of event.choices) {
      const delta = choice.delta?.content;
      if (delta !== undefined) {
        console.log(`Chatbot: ${delta}`);
      }
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

轉譯和翻譯音訊檔案

Azure OpenAI 的語音轉換文字和翻譯功能可用來轉譯和翻譯各種不同的音訊檔格式。下列範例示範如何使用 getAudioTranscription 方法來將音頻轉譯成音訊所在的語言。您也可以使用 getAudioTranslation 方法將音訊翻譯並轉譯成英文。

音訊檔案可以使用 NodeJS 檔案系統 API 載入記憶體中。在瀏覽器中，可以使用 API 載入 FileReader 檔案，而實例方法的 arrayBuffer 輸出可以傳遞至 getAudioTranscription 方法。

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");
const fs = require("fs/promises");

async function main() {
  console.log("== Transcribe Audio Sample ==");

  const client = new OpenAIClient(endpoint, new AzureKeyCredential(azureApiKey));
  const deploymentName = "whisper";
  const audio = await fs.readFile("< path to an audio file >");
  const result = await client.getAudioTranscription(deploymentName, audio);

  console.log(`Transcription: ${result.text}`);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

使用 gpt-4-vision-preview 與影像聊天

此 gpt-4-vision-preview 模型可讓您使用影像作為聊天完成的輸入元件。

若要這樣做，請在使用者訊息上提供不同的內容專案， (的聊天完成要求) ：

const url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
const deploymentName = "gpt-4-1106-preview";
const messages: ChatRequestMessage[] = [{role: "user", content: [{
  type: "image_url",
  imageUrl: {
    url,
    detail: "auto"
  }
}]}];

聊天完成接著會如往常一樣繼續，不過模型可能會回報更豐富的資訊 finish_details ，而不是 finish_reason：

const result = await client.getChatCompletions(deploymentName, messages);
console.log(`Chatbot: ${result.choices[0].message?.content}`);

疑難排解

記錄

啟用記錄有助於找出失敗的相關實用資訊。若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

共用方式為

適用於 JavaScript 的 Azure OpenAI 用戶端連結庫 - 1.0.0-beta.12 版

開始使用

目前支援的環境

必要條件

安裝 `@azure/openai` 套件

建立和驗證 `OpenAIClient`

從 Azure 使用 API 金鑰

使用 Azure Active Directory 認證

從 OpenAI 使用 API 金鑰

重要概念

範例

產生 Chatbot 回應

使用訂用帳戶金鑰產生多個完成

完成的摘要文字

使用聊天工具

使用 DALL-E 映射產生模型產生影像

分析商務數據

轉譯和翻譯音訊檔案

使用 gpt-4-vision-preview 與影像聊天

疑難排解

記錄

其他資源

共用方式為

適用於 JavaScript 的 Azure OpenAI 用戶端連結庫 - 1.0.0-beta.12 版

開始使用

目前支援的環境

必要條件

安裝 @azure/openai 套件

建立和驗證 OpenAIClient

從 Azure 使用 API 金鑰

使用 Azure Active Directory 認證

從 OpenAI 使用 API 金鑰

重要概念

範例

產生 Chatbot 回應

使用訂用帳戶金鑰產生多個完成

完成的摘要文字

使用聊天工具

使用 DALL-E 映射產生模型產生影像

分析商務數據

轉譯和翻譯音訊檔案

使用 gpt-4-vision-preview 與影像聊天

疑難排解

記錄

其他資源

安裝 `@azure/openai` 套件

建立和驗證 `OpenAIClient`