JavaScript용 Azure OpenAI Assistants 클라이언트 라이브러리 - 버전 1.0.0-beta.5

아티클
03/02/2024

JavaScript용 Azure OpenAI Assistants 클라이언트 라이브러리는 Idiomatic 인터페이스를 제공하고 나머지 Azure SDK 에코시스템과 풍부한 통합을 제공하는 OpenAI의 REST API를 적응한 것입니다. Azure OpenAI 리소스 또는 비 Azure OpenAI 유추 엔드포인트에 연결할 수 있으므로 비 Azure OpenAI 개발에도 적합합니다.

주요 링크:

시작

현재 지원되는 환경

Node.js의 LTS 버전
최신 버전의 Safari, Chrome, Edge, Firefox.

사전 요구 사항

Azure OpenAI 리소스를 사용하려면 Azure 구독 및 Azure OpenAI 액세스 권한이 있어야 합니다. 이렇게 하면 Azure OpenAI 리소스를 만들고 연결 URL과 API 키를 모두 가져올 수 있습니다. 자세한 내용은 빠른 시작: Azure OpenAI Service를 사용하여 텍스트 생성 시작을 참조하세요.

Azure OpenAI Assistants JS 클라이언트 라이브러리를 사용하여 비 Azure OpenAI에 연결하려면 의 개발자 계정 https://platform.openai.com/에서 API 키가 필요합니다.

`@azure/openai-assistants` 패키지를 설치합니다.

를 사용하여 JavaScript용 Azure OpenAI Assistants 클라이언트 라이브러리를 npm설치합니다.

npm install @azure/openai-assistants

`AssistantsClient` 만들기 및 인증

Azure OpenAI에서 사용할 클라이언트를 구성하려면 Azure OpenAI 리소스를 사용할 수 있는 권한이 부여된 해당 키 자격 증명, 토큰 자격 증명 또는 Azure ID 자격 증명과 함께 Azure OpenAI 리소스에 유효한 엔드포인트 URI를 제공합니다. 대신 OpenAI의 서비스에 연결하도록 클라이언트를 구성하려면 OpenAI의 개발자 포털에서 API 키를 제공합니다.

Azure에서 API 키 사용

Azure Portal을 사용하여 OpenAI 리소스로 이동하고 API 키를 검색하거나 아래 Azure CLI 코드 조각을 사용합니다.

참고: API 키를 "구독 키" 또는 "구독 API 키"라고도 합니다.

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

주요 개념

도우미와 함께 사용되는 개념 및 관계에 대한 개요는 OpenAI의 "도우미 작동 방식" 설명서를 참조하세요. 이 개요는 OpenAI의 개요 예제 에 따라 도우미 및 스레드를 만들고, 실행하고, 사용하는 기본 사항을 보여 줍니다.

시작하려면 을 만듭니다 AssistantsClient.

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

클라이언트를 사용하면 도우미 만들 수 있습니다. 도우미 도구는 도우미 수명 동안 개략적인 지침을 허용하면서 도구를 호출할 수 있는 OpenAI 모델에 대한 특별히 빌드된 인터페이스입니다.

도우미 만드는 코드:

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

도우미와 사용자 간의 대화 세션을 스레드라고 합니다. 스레드는 메시지를 저장하고 콘텐츠를 모델의 컨텍스트에 맞게 잘림을 자동으로 처리합니다.

스레드를 만들려면 다음을 수행합니다.

const assistantThread = await assistantsClient.createThread();

메시지는 도우미 또는 사용자가 만든 메시지를 나타냅니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드의 목록으로 저장됩니다. 스레드를 만들면 메시지를 만들 수 있습니다.

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

실행은 스레드에서 도우미의 호출을 나타냅니다. 도우미는 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 도우미는 스레드에 메시지를 추가합니다. 그런 다음 도우미 대해 스레드를 평가하는 실행을 시작할 수 있습니다.

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

실행이 시작되면 터미널 상태 도달할 때까지 폴링되어야 합니다.

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

실행이 성공적으로 완료되었다고 가정하면 실행된 스레드의 메시지를 나열하면 이제 도우미 추가된 새 정보가 반영됩니다.

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

이 시퀀스의 출력 예제:

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?

검색을 위해 파일 작업

파일을 업로드한 다음 도우미 또는 메시지에서 참조할 수 있습니다. 먼저 'assistants'를 목적으로 일반화된 업로드 API를 사용하여 파일 ID를 사용할 수 있도록 합니다.

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

업로드되면 파일 ID를 만들 때 도우미 제공할 수 있습니다. 파일 ID는 코드 인터프리터 또는 검색과 같은 적절한 도구를 사용하도록 설정한 경우에만 사용됩니다.

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

파일 ID 연결 및 지원되는 도구를 사용하도록 설정하면 도우미 스레드를 실행할 때 연결된 데이터를 사용할 수 있습니다.

함수 도구 및 병렬 함수 호출 사용

도우미 도구에 대한 OpenAI 설명서에 설명된 대로 호출자 정의 기능을 함수로 참조하는 도구를 도우미 제공하여 실행 중에 동적으로 resolve 명확하게 할 수 있습니다.

여기서는 호출자가 제공하는 함수를 통해 "방법을 알고 있다"는 간단한 도우미 간략하게 설명합니다.

사용자가 가장 좋아하는 도시 가져오기
지정된 도시에 대한 애칭 가져오기
도시의 온도 단위를 사용하여 현재 날씨를 선택적으로 가져옵니다.

이렇게 하려면 먼저 사용할 함수를 정의합니다. 여기서 실제 구현은 단지 대표적인 스텁일 뿐입니다.

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

적절한 도구에 정의된 함수를 사용하면 이제 해당 도구를 사용하도록 설정된 도우미 만들 수 있습니다.

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

도우미 도구를 호출하는 경우 호출 코드는 인스턴스를 일치하는 ToolOutputSubmission 인스턴스로 resolve ToolCall 합니다. 편의를 위해 기본 예제는 여기에서 추출됩니다.

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

"내가 가장 좋아하는 도시에서 지금 날씨는 어때?"와 같은 사용자 입력을 처리하려면 완료에 대한 응답을 폴링하는 검사 RequiresAction 보완 RunStatus 해야 합니다. 이 경우 실행에 속성이 RequiredAction 존재합니다. 그런 다음, 실행을 계속할 수 있도록 의 ToolOutputSubmissions 컬렉션을 메서드를 SubmitRunToolOutputs 통해 실행에 제출해야 합니다.

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

지원되는 모델을 사용하는 경우 도우미 여러 함수를 병렬로 호출할 것을 요청할 수 있습니다. 이전 모델은 한 번에 하나의 함수만 호출할 수 있습니다.

필요한 모든 함수 호출이 해결되면 실행이 정상적으로 진행되며 스레드의 완료된 메시지에는 제공된 함수 도구 출력으로 보완된 모델 출력이 포함됩니다.

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

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

setLogLevel("info");

로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.

Share via

JavaScript용 Azure OpenAI Assistants 클라이언트 라이브러리 - 버전 1.0.0-beta.5

시작

현재 지원되는 환경

사전 요구 사항

`@azure/openai-assistants` 패키지를 설치합니다.

`AssistantsClient` 만들기 및 인증

Azure에서 API 키 사용

주요 개념

검색을 위해 파일 작업

함수 도구 및 병렬 함수 호출 사용

문제 해결

로깅

피드백

추가 리소스

Share via

JavaScript용 Azure OpenAI Assistants 클라이언트 라이브러리 - 버전 1.0.0-beta.5

시작

현재 지원되는 환경

사전 요구 사항

@azure/openai-assistants 패키지를 설치합니다.

AssistantsClient 만들기 및 인증

Azure에서 API 키 사용

주요 개념

검색을 위해 파일 작업

함수 도구 및 병렬 함수 호출 사용

문제 해결

로깅

피드백

추가 리소스

`@azure/openai-assistants` 패키지를 설치합니다.

`AssistantsClient` 만들기 및 인증