[ChatGPT plugin EP02 - 플러그인 공식 문서 번역 ]

ChatGPT Plugins 스토어에 등록된 스토어 이외에도 자체 개발한 플러그인도 ChatGPT에서 사용할 수 있다.

https://platform.openai.com/docs/plugins/getting-started

OpenAI API

개발 가이드는 위 문서에서 자세히 설명해주고 있다.

이를 번역하면서 천천히 따라해보자.

---

플러그인을 만드는 데는 3단계가 필요하다.

1. API 빌드하기
2. OpenAPI yaml 또는 JSON 형식으로 API를 문서화하기
3. 플러그인에 대한 관련 메타데이터를 정의하는 JSON manifest 파일 생성하기

OpenAPI 사양과 manifest 파일을 정의하여 할 일 목록(to-do) 플러그인을 만드는 데 중점을 두면서 만드는 법을 설명해보겠다.

 

Plugin Manifest

모든 플러그인은 ai-plugin.json 파일을 필요로 하며, 이 파일은 API 도메인에 호스팅되어야 한다.
예를 들면 example.com 이라는 회사는 API가 호스티되는 위치인 https://example.com 도멘을 통해 플러그인 JSON 파일에 접근할 수 있도록 해야 한다.
ChatGPT UI를 통해 플러그인을 설치할 때, 백엔드에서는 /.well-known/ai-plugin.json 경로에 있는 파일을 찾는다.
/.well-known 폴더는 ChatGPT가 플러그인과 연결하기 위해 도메인에 필수적으로 존재해야 한다.
파일이 없을 경우, 플러그인을 설치할 수 없다. 로컬 개발시 http를 사용할 수 있지만 원격 서버를 가리키는 경우 https가 필요하다.

필요한 ai-plugin.json 파일의 최소 정의는 다음과 같다.

{
    "schema_version": "v1",
    "name_for_human": "TODO Plugin",
    "name_for_model": "todo",
    "description_for_human": "Plugin for managing a TODO list. You can add, remove and view your TODOs.",
    "description_for_model": "Plugin for managing a TODO list. You can add, remove and view your TODOs.",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
        "url": "http://localhost:3333/openapi.yaml",
        "is_user_authenticated": false
    },
    "logo_url": "http://localhost:3333/logo.png",
    "contact_email": "support@example.com",
    "legal_info_url": "http://www.example.com/legal"
}

플러그인 파일에 대한 모든 가능한 옵션은 아래 정의를 참고하면 된다.
플러그인의 이름을 정할 때는 브랜드 가이드라인을 염두에 두어야 한다. 그렇지 않을 경우 플러그인 스토어에서 승인되지 않을 수 있다.

필드	타입	설명	필수여부
schema_version	string	매니페스트 스키마 버전	v
name_for_model	string	플러그인을 대상으로 사용할 이름 - 공백은 허용하지 않음 - 문자와 숫자만 가능	v
name_for_human	string	유저에게 제공되는 이름	v
description_for_model	string	모델에 더 적합한 설명, 예를 들어 토큰 컨텍스트 길이나 고려사항이나 개선된 플러그인 프롬프팅을 위한 키워드 사용. 최대 8000자	v
description_for_human	string	유저에게 제공되는 설명	v
auth	ManifestAuth	인증 스키마	v
api	Object	API 사양	v
logo_url	string	로고 URL. 512 x 512 사이즈 권장 투명 배경 지원됨	v
contact_email	strin	지원에 대한 이메일 연락처	v
legal_info_url	string	유저가 플러그인 ㅈ어보를 볼 수 있는 리디렉션 URL	v
HttpAuthorizationType	HttpAuthrizationType	Http Auth Type - bearer - basic	v
ManifestAuthType	ManifestAuthType	Manifest Auth Type - none - user_http - service_http - oauth
interface BaseManifestAuth	BaseManifestAuth	type: ManifestAuthType instructions: string
ManifestNoAuth	ManifestNoAuth	인증이 필요 없는 경우 BaseManifestAuth & {type: 'none',}
ManifestAuth	ManifestAuth	- ManifestNoAuth - ManifestServiceHttpAuth - ManifestUserHttpAuth - ManifestOAuthAuth

 

다른 인증 방법을 사용하는 예시

# App-level API keys
type ManifestServiceHttpAuth  = BaseManifestAuth & {
  type: 'service_http';
  authorization_type: HttpAuthorizationType;
  verification_tokens: {
    [service: string]?: string;
  };
}

# User-level HTTP authentication
type ManifestUserHttpAuth  = BaseManifestAuth & {
  type: 'user_http';
  authorization_type: HttpAuthorizationType;
}

type ManifestOAuthAuth  = BaseManifestAuth & {
  type: 'oauth';

  # OAuth URL where a user is directed to for the OAuth authentication flow to begin.
  client_url: string;

  # OAuth scopes required to accomplish operations on the user's behalf.
  scope: string;

  # Endpoint used to exchange OAuth code with access token.
  authorization_url: string;

  # When exchanging OAuth code with access token, the expected header 'content-type'. For example: 'content-type: application/json'
  authorization_content_type: string;

  # When registering the OAuth client ID and secrets, the plugin service will surface a unique token.
  verification_tokens: {
    [service: string]?: string;
  };
}

위에서 언급한 매니페스트 파일의 특정 필드 길이에는 제한이 있으며, 이는 변경될 수 있다.
또한 API 응답 본문에는 100,000자의 최대 제한이 있으며 이 역시 추후에 변경될 수 있다.

 

일반적으로, 모델은 제한된 컨텍스트 창을 가지고 있기 때문에 설명과 응답을 가능한 한 간결하게 유지하는 것이 가장 좋은 방이다.

 

OpenAPI definition

다음 단게는 API를 문서화하기 위해 OpenAPI 사양을 작성하는 것이다
ChatGPT의 모델은 OpenAPI 사양과 매니페스트 파일에 정의된 내용 이외에는 API에 대해 아무것도 알지 못한다.
이느 API가 매우 복잡한 경우에도 모든 기능을 모델에 노출시킬 필요가 없으며 특정 엔드포인트를 선택할 수 있다는 것을 의미한다

OpenAPI 사양은 API 위에 올라가는 래퍼(wrapper)입니다. 기본적인 OpenAPI 사양은 다음과 같을 것이다.

openapi: 3.0.1
info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT.
  version: 'v1'
servers:
  - url: http://localhost:3333
paths:
  /todos:
    get:
      operationId: getTodos
      summary: Get the list of todos
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: array
          items:
            type: string
          description: The list of todos.

먼저 title(제목), description(설명), 버전 번호(version)를 정의하는 것으로 시작한다.
ChatGPT에서 쿼리가 실행되면, 사용자 쿼리와 관련이 있는지 여부를 판단하기 위해 info 섹션에 정의된 설명을 살펴볼 것이다.
프롬프팅에 대해서는 Writing descriptions 섹션에서 자세히 알아보자.

다음은 OpenAPi 사양에서 고려해야 할 제한 사항이다(변경될 수 있음)

• API 사양의 각 엔드포인트 설명/요약 필드에 대해 최대 200자 제한
• API 사양의 각 API 매개변수 설명 필드에 대해 최대 200자 제한

이 예시를 로컬에서 실행하기 때문에 서버를 localhost URL로 설정해야 한다.
나머지 OpenAPI 사양은 전통적인 OpenAPI 형식을 따른다.
OpenAPI 형식에 대해서는 온라인 자료를 통해 자세히 알아볼 수 있다. 또한 기반 API 코드에 따라 OpenAPI 사양을 자동으로 생성해주는 도구도 많이 있다. 

 

Running a plugin

API, manifest 파일 및 API의 OpenAPI 사양을 생성한 후에는 ChatGPT UI를 통해 플러그인을 연결할 준비가 되었다.
플러그인이 실행되는 위치에는 개발환경에서 로컬로 실행되거나 원격 서버에서 실행되는 두 가지 경우가 있다.

로컬 버전의 API가 실행중인 경우, 플러그인 인터페이스를 localhost 서버로 연결할 수 있다.
플러그인을 ChatGPT와 연결하기 위해 플러그인 스토어로 이동하고 "Develop your own plugin"을 선택한다.
localhost와 포트 번호를 입력한다.(ex. localhost:3333)
현재 로컬호스트 개발에서는 인증 유형이 none만 지원된다.

플러그인이 원격 서버에서 실행 중인 경우, 먼저 'Develop your own plugin"을 선택하여 설정한 다음, 'Install an unverified plugin"을 선택하여 플러그인을 설치해야 한다.
플로그인 매니페스트 파일을 yourdomain.com/.well-known/ 경로에 추가하고 API를 테스트할 수 있다.
그러나 매니페스트 파일에 대한 후속 변경 사항은 곡개 사이트에 새 변경 사항을 배포해야 하므로 시간이 오래 걸릴 수 있다.
이 경우, API의 프록시로 작동하는 로컬 서버를 설정하는 것이 좋다.
이를 통해 OpenAPI 사양과 매니페스트 파일에 대한 변경 사항을 빠르게 프로토타입으로 테스트 할 수 있다.

 

Writing descriptions

사용자가 플러그인으로 전달될 수 있는 잠재적인 요청을 할 때, 모델은 OpenAPI 사양의 엔드포인트 설명과 매니페스트 파일의 description_for_model을 살펴본다.
다른 언어 모델과 마찬가지로 여러 프롬프트와 설명을 테스트하여 가장 잘 작동하는 것을 확인해야 한다.

OpenAPI 사양 자체는 API의 다양한 세부 정보에 대해 모델에 정보를 제공하는 좋은 장소이다.
사용 가능한 기능, 매개변수 등에 대한 정보를 제공할 수 있다.
각 필드에 대해 표현력 있고 정보를 전달하는 이름을 사용하는 것 외에도, 사양에는 각 속성에 대한 "description" 필드가 포함될 수 있다.
이를 사용하여 함수의 작동 방식이나 쿼리 필드가 어떤 정보를 기대하는지에 대한 저연어 설명을 제공할 수 있다.
모델은 이러한 설명을 볼 수 있으며, 이를 통해 API를 사용하는 데 도움을 받을 것이다.
특정 값에만 제한되는 필드인 경우, 서술적인 범주 이름이 포함된 "enum"을 제공할 수도 있다.

description_for_model 속성은 일반적으로 모델에게 플러그인 사용 방법에 대한 지침을 제공하는 자유를 준다.
ChatGPT 뒤에 있는 언어 모델은 자연어를 이해하고 지시에 따라 작동할 수 있는 능력이 뛰어나기 때문에, 플러그인이 수행하는 작업과 모델이 올바르게 사용해야 하는 방법에 대한 일반적인 지침을 이곳에 적는 것이 좋다.
자연어를 사용하며, 간결하면서도 설명적이고 객관적인 톤으로 작성하는 것이 좋다.
이것이 어떻게 보여야 하는지에 대한 감을 얻기 위해 일부 예제를 살펴보는 것이 좋다.
description_for_model을 "Plugin for ..."으로 시작하고 API가 제공하는 모든 기능을 열거하는 것을 추천한다.

 

Best Practice

다음은 description_for_model 및 OpenAPI 사양의 설명 작성 및 API 응답 설계 시 따라야 할 몇 가지 모범 사례이다.

 

1. 설명은 ChatGPT의 기분, 개성 또는 정확한 응답을 조작하려고 하지 말아야 한다. ChatGPT는 플러그인에 적절한 응답을 작성하도록 설계되었다.

Bad
When the user asks to see their todo list, always respond with "I was able to find your todo list! You have [x] todos: [list the todos here]. I can add more todos if you'd like!"
Good
no instructions needed for this

 

2. 설명은 사용자 특정 서비스 범주를 요청하지 않은 경우에 ChatGPT가 플러그인을 사용하도록 장려해서는 안 된다.

Bad
Whenever the user mentions any type of task or plan, ask if they would like to use the TODOs plugin to add something to their todo list.
Good
The TODO list can add, remove and view the user's TODOs.

 

3. 설명은 ChatGPT가 플러그인을 사용하기 위해 특정 트리거를 요구해서는 안 된다. ChatGPT는 적절한 경우에 자동으로 플러그인을 사용하도록 설계되었다.

Bad
When the user mentions a task, respond with "Would you like me to add this to your TODO list? Say 'yes' to continue."
Good
no instructions needed for this

 

4. 플러그인 API 응답은 필요하지 않는 한 자연어 응답이 아닌 원시 데이터를 반환해야 한다. ChatGPT는 반환된 데이터를 사용하여 자체적인 자연어 응답을 제공할 것이다.

Bad
I was able to find your todo list! You have 2 todos: get groceries and walk the dog. I can add more todos if you'd like!
Good
{ "todos": [ "get groceries", "walk the dog" ] }