CURL, Postman

채연·2023년 3월 17일
0

ChatGPT

목록 보기
2/2

코드를 작성하지 않고, API 엔드포인트를 호출하고 싶은 경우에 사용하는 개발자 도구 CURL과 Postman에 대해서 알아보겠습니다.

CURL

curl은 1998년부터 존재하기 때문에 널리 사용됩니다. Linux, Mac, Windows에서 사용할 수 있으며, 대부분의 컴퓨터에도 기본적으로 설치됩니다.

CURL이 설치되었는지 확인하려면 명령 줄에 curl --help 명령어를 입력하면 확인할 수 있습니다.

설치가 됐다면 위와 같은 화면이 표시됩니다.

CURL이 설치되어 있지 않은 경우 공식 CURL 사이트에서 다운로드 할 수 있습니다. CURL은 API 작업 뿐아니라 모든 HTTP 요청에 사용할 수 있습니다.

예를들어, 명령 프롬포트에서 curl https://dabblelab.com 을 입력하고 엔터키를 누르면 CURL은 debblelab.com 홈페이지를 가져옵니다.
그러나, CURL은 브라우저가 아니므로 원시 HTML 코드를 볼 수 있습니다.

Postman

postman은 curl과 달리 그래픽 사용자 인터페이스를 가지고 있습니다. 따라서, 명령 줄이 익숙하지 않은 경우에는 Postman을 사용하면 됩니다.
브라우저에서 사용할 수 있고, 소프트웨어를 설치하여 사용할 수도 있습니다.
공식 사이트에서 계정을 등록하면 바로 사용 가능합니다.

Postman을 사용하여 API 요청하는 방법을 보여주는 튜토리얼을 해보겠습니다.
1. Postman.com에 로그인 한 후, Create New 링크를 클릭하세요. 데스크톱을 다운로드 하라는 말이 나오면 skip 하셔도 됩니다.

  1. 더하기 기호를 클릭하여 새 탭을 연 후, 요청 URL에 http://api.open-notify.org/astros.json 를 입력하고, 보내기 버튼을 누릅니다.

-> 위에 사진에서 보이듯 Postman은 JSON 결과를 읽기 쉬운 방식으로 포맷팅해줍니다.


OpenAI API 사용하기

Open-Notify API는 일반인에게 공개되어있고, 인증이 필요하지 않은 반면, OpenAI API는 비공개적이며 사용을 위해 인증이 필요합니다.

API가 애플리케이션 요청을 인증하는 방법 중 하나인 기본 인증에 대해서 알아보겠습니다.
OpenAI API는 이 기본 인증을 사용합니다.

기본 인증

기본인증은 HTTP에서 사용되는 네이티브 인증 방법입니다. 이 방법은 HTTP 헤더에 사용자 이름과 비밀번호를 포함시킵니다. 요청과 응답을 암호화 하기 위하여, 기본 인증을 사용하는 API 엔드 포인트 URL은 항상 SSL을 사용해야 합니다. SSL을 사용하면 HTTP가 아닌 HTTPS로 시작하게 됩니다.

OpenAI API는 사용자 이름과 비밀번호 대신 API 키라는 것을 사용하게 되는데, 이것은 사용자 이름과 비밀번호가 합쳐진 문자열과 같은 역할을 합니다.

API 키가 있으면 OpenAI API에 요청을 보낼 수 있는 모든 것이 갖추어 진 것입니다.

잠깐! API 비공개 유지의 중요성

API는 쉽게 변경될 수 있지만, 계정에 대한 액세스를 제공하기 때문에 비공개로 유지해야 합니다.

OpenAI API에 인증된 요청 보내기

인증된 요청을 보내기 위해서는 먼저 API 키를 HTTP 헤더의 일부로 포함해야 합니다. 사용할 헤더 이름은 "authorization"이며, 값은 Bearer 뒤에 공백을 두고 API 키를 붙입니다. 이렇게 API 키를 사용하는 경우 Bearer token이라고 합니다.

postman은 이 Bearer 토큰 사용을 매우 간편하게 만들어줍니다.
인증된 요청을 하기 전에 인증되지 않은 요청부터 보내보겠습니다.

위의 사진은 인증 헤더 없이 요청을 보낸 것입니다. 401 UNAUTHORIZED가 뜨며, 오류 코드를 반환하는 것을 볼 수 있습니다.
-> 이 오류를 해결하려면 bearer 토큰으로 API 키를 포함해야 합니다.

Postman 변수 설정

postman에서 변수를 사용하여 API 키를 저장하면 반복하지 않고 계속 재사용할 수 있습니다.

  1. 우측 상단의 눈 아이콘을 클릭합니다.

  2. Add를 클릭하여 새 환경을 추가합니다.

  3. 환경 이름은 openai-dev로 지정합니다.

  4. OPENAI_API_KEY라는 변수를 추가합니다.

  5. 초기 값에는 API 키를 입력합니다.

  6. 저장 후 환경 옵션 목록에서 openai-dev 환경을 추가합니다.

    -> 이렇게 설정하시면, OPENAI_API_KEY 변수가 준비되고 실제 키 값을 대신하여 {{OPENAI_API_KEY}}를 사용합니다.


인증 헤더 설정

  1. 요청 URL 입력란에 인증 탭을 클릭합니다.
  2. type에서 Bearer Token 옵션을 선택합니다.
  3. Token 입력란에 아까 설정했던 변수인 {{OPENAI_API_KEY}}를 입력합니다.
  4. SEND 눌러주면 성공!


-> 실패 떴던 아까와 다르게 성공하여 JSON을 받아오는 것을 확인할 수 있습니다.


여러 조직

여러 조직과 연관된 사용자 계정일 때는 API 요청을 특정 조직과 연관시키기 위해 OpenAI-Organization HTTP 헤더와 해당 조직의 ID를 포함해야 합니다.


-> 새로운 헤더를 헤더 탭에 추가하고, 이름은 OpenAI-Organization으로 지정한 후, 계정과 연관된 조직 ID를 값으로 설정하면 됩니다!
-> 위에서 했던 것과 같이 변수로 설정도 가능합니다.

CURL을 사용하여 인증된 API 호출하기

CURL에서는 HTTP 헤더를 명령 줄 매개변수로 전달합니다.

curl https://api.openai.com/v1/engines
-H 'Authorization: Bearer {your-api-key}'
-H 'OpenAI-Organization: {your-orgainzation-id}'

JSON이란?

JSON은 가벼우며 기계가 파싱하기 쉽고 인간이 읽기 쉬운 인기있는 데이터 교환 형식입니다.

JSON 구문은 javascript 프로그래밍 언어의 하위 집합을 기반으로 하며,
1. name/value 쌍의 모음
2. 값의 정렬된 list
이러한 두 가지 데이터 구조를 정의합니다.

이 두 데이터 구조는 모든 프로그래밍 언어에서 어떤 방식으로든 지원이 됩니다.
따라서, 다른 언어랑도 쉽게 사용할 수 있습니다.

JSON의 두 가지 데이터 구조는 객체 혹은 배열로 정의됩니다.

객체

객체는 {로 시작해서 }로 끝나고, 요소라고 하는 name/value 세트를 포함할 수도 있습니다.
특정한 순서가 필요없고, 숫자, boolean, null, 다른 객체 또는 배열이 될 수 있습니다.
이름과 값은 콜론으로 구분되고, 요소는 쉼표로 구분됩니다.

{
"id": "cmpl-2T0IrOkctsOm8uVFvDDEmc1712U9R",
"object": "text_completion",
"created": 1613265353,
"model": "davinci:2020-05-03",
"choices": [
{
"text": ", there was a dog",
"index": 0,
"logprobs": null,
"finish_reason": "length"
}]}

배열

배열은 값들의 순서가 지정된 컬렉션입니다. 값들은 문자열, 숫자, boolean, null, 객체 혹은 다른 배열의 컬렉션이 될 수 있습니다. 객체와 달리 대괄호로 시작하고 대괄호로 끝납니다. 또한 값들은 쉼표로 구분됩니다.

{"question":"Is this correct? ","answer":"Yes"}

탭, 공백 및 줄바꿈은 인간이 읽기 쉽게 하기 위해서만 사용됩니다.

예시 1:
{"question":"Is this correct? ","answer":"Yes"}
예시 2:
{
"question" : "Is this correct?",
"answer" : "Yes"
}

위의 두 코드는 같습니다.


Completions 엔드포인트 사용하기

OpenAI API를 사용할 때는 대부분 Completions 엔드포인트를 사용합니다. completions 엔드포인트는 List Engines 엔드포인트보다 조금 더 복잡한데, HTTP POST 방식을 사용하고 본문으로 JSON 객체를 필요로 하기 때문입니다.

Postman으로 호출하기

  1. 요청 유형을 POST로 설정합니다.
  2. 엔드포인트로 https://api.openai.com/v1/engines/davinci/completions 를 입력합니다.
  3. 본문을 Raw로 설정합니다.
  4. 본문 내용 유형으로 JSON을 선택합니다.
  5. JSON 본문 텍스트로 {"prompt": "Once upon a time"}을 입력합니다.

    -> 이렇게 설정하면 값이 잘 나오는 것을 볼 수 있습니다.

여러가지 매개변수 사용하기

엔드포인트는 여러 추가 매개 변수를 허용합니다. 추가 매개 변수를 포함하기 위해서는 JSON 본문 객체의 요소로 포함해야 합니다.

{"prompt" : "Once upon a time",
 "max_tokens" : 4
}

-> 위의 예시는 max_tokens의 추가 매개변수를 포함한 예시입니다.

추가 매개변수는 위와 같은 방식으로 추가해주면 되고, 다른 매개변수 목록들은 https://beta.openai.com/docs/api-reference/create-completion <- 여기에서 확인하실 수 있습니다.

동시에 여러 prompt 보내기

{
"prompt": ["The capital of California is:", "Once upon a
time"],
"max_tokens":7,
"temperature": 0,
"stop": "\n"
}

propmpt의 값이 "The captial of California is" 와 "Once upon a time" 으로 주어지니

prompt에 대한 완성 답변도 두 개 보내주게 됩니다.


의미론적 검색

시맨틱 검색은 제공된 문서 목록에서 Google과 유사한 검색을 수행할 수 있습니다. 쿼리는 문서 내용과 비교되어 시맨틱 유사성이 있는지 여부를 결정합니다. 결과는 각 문서에 대한 랭킹 혹은 점수로 표시됩니다. 점수는 일반적으로 0~300 사이지만, 더 높아질 수도 있습니다.

시맨틱 검색을 수행하기 위해서는 POST 요청을 보내야 합니다. JSON 본문 객체에는 documents 요소와 query 요소 두 개의 요소가 있습니다. documents 요소는 검색할 문서의 배열이며, 배열의 각 항목은 문서를 나타내는 문자열입니다.

** 시맨틱 검색은 유사한 단어를 찾는 것이 아닌, 쿼리와 문서가 얼마나 유사한지를 평가하는 것입니다.

예) 비행기, 보트, 우주선 또는 자동차를 제공하고 "바퀴가 있는 차량"이라는 쿼리를 제공합니다.

{
"documents": [
"plane",
"boat",
"spaceship",
"car"
],
"query": "A vehicle with wheels"
}

시맨틱 검색의 엔드포인트 URI는 https://api.openai.com/v1/engines/{engine_id}/search 이곳으로, {engine_id}는 유효한 엔진 ID (davinci, ada)로 대체됩니다.

https://api.openai.com/v1/engines/davinci/search 로 위의 코드를 제출하게 되면, 배열 차례대로 결과가 나옵니다.

{
"object": "list",
"data": [
{
"object": "search_result",
"document": 0,
"score": 56.118
},
{
"object": "search_result",
"document": 1,
"score": 46.883
},
{
"object": "search_result",
"document": 2,
"score": 94.42
},
{
"object": "search_result",
"document": 3,
"score": 178.947
}
],
"model": "davinci:2020-05-03"
}

받은 데이터는 3(자동차)가 가장 높은 점수를 받았으며, 가장 의미론적으로 유사하다는 것을 알 수 있습니다.
-> 문서가 아닌 숫자로 나타내는 이유는 문서가 긴 텍스트 문자열일 가능성도 있고, 문서 번호를 사용하는 것이 훨씬 효율적이기 때문입니다.


profile
Hello Velog

0개의 댓글