translated_Function_calling_with_an_OpenAPI_spec.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "8317718bcd8b475e9b336514241d679e",
    "deepnote_cell_type": "text-cell-h1",
    "formattedRanges": []
   },
   "source": [
    "# OpenAPI 사양으로 함수 호출하기\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "6f810c4e582c41a1bd3bdfc4263dee89",
    "deepnote_cell_type": "text-cell-p",
    "formattedRanges": []
   },
   "source": [
    "인터넷의 대부분은 RESTful API로 구동됩니다. GPT에 이러한 API를 호출할 수 있는 기능을 부여하면 가능성의 세계가 열립니다. 이 노트북에서는 GPT를 사용하여 API를 지능적으로 호출하는 방법을 보여드립니다. 여기에서는 OpenAPI 사양과 연쇄 함수 호출을 활용합니다.\n",
    "\n",
    "OpenAPI 사양(OAS)](https://swagger.io/specification/)은 기계가 읽고 해석할 수 있는 형식으로 RESTful API의 세부 사항을 설명하기 위해 보편적으로 인정되는 표준입니다. 이를 통해 인간과 컴퓨터 모두 서비스의 기능을 이해할 수 있으며, GPT에 API를 호출하는 방법을 표시하는 데 활용할 수 있습니다.\n",
    "\n",
    "이 노트북은 두 개의 주요 섹션으로 나뉩니다:\n",
    "\n",
    "1. 샘플 OpenAPI 사양을 채팅 완료 API의 함수 정의 목록으로 변환하는 방법.\n",
    "2. 채팅 완료 API를 사용하여 사용자 지침에 따라 이러한 함수를 지능적으로 호출하는 방법.\n",
    "\n",
    "이 절차를 진행하기 전에 [함수 호출](./How_to_call_functions_with_chat_models.ipynb)을 숙지하는 것이 좋습니다.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "cell_id": "bf983b3e199d4ea6a2718e58a141bd88",
    "deepnote_cell_type": "code",
    "deepnote_to_be_reexecuted": false,
    "execution_millis": 10617,
    "execution_start": 1697419508239,
    "source_hash": "d6b9a6d3"
   },
   "outputs": [],
   "source": [
    "!pip install -q jsonref # for resolving $ref's in the OpenAPI spec\n",
    "!pip install -q openai"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "cell_id": "12fb12583cc74b7c842a1b4656b94f47",
    "deepnote_cell_type": "code",
    "deepnote_to_be_reexecuted": false,
    "execution_millis": 10,
    "execution_start": 1697419706563,
    "source_hash": "750280cb"
   },
   "outputs": [],
   "source": [
    "import os\n",
    "import json\n",
    "import jsonref\n",
    "import openai\n",
    "import requests\n",
    "from pprint import pp\n",
    "\n",
    "openai.api_key = os.environ[\"OPENAI_API_KEY\"]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "76ae868e66b14cc48c9c447302ea268e",
    "deepnote_cell_type": "text-cell-h2",
    "formattedRanges": []
   },
   "source": [
    "## OpenAPI 사양을 함수 정의로 변환하는 방법\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "9cf167d2d5fe4d7eadb69ba18db4a696",
    "deepnote_cell_type": "text-cell-p",
    "formattedRanges": []
   },
   "source": [
    "여기서 사용하는 예제 OpenAPI 사양은 `gpt-4`를 사용하여 만들었습니다. 이 샘플 사양을 채팅 완료 API에 제공할 수 있는 함수 정의 집합으로 변환하겠습니다. 제공된 사용자 지침에 따라 모델은 이러한 함수를 호출하는 데 필요한 인수가 포함된 JSON 객체를 생성합니다.\n",
    "\n",
    "계속 진행하기 전에 생성된 사양을 살펴보겠습니다. OpenAPI 사양에는 API의 엔드포인트, 지원하는 작업, 허용하는 매개변수, 처리할 수 있는 요청 및 반환하는 응답에 대한 세부 정보가 포함됩니다. 사양은 JSON 형식으로 정의됩니다.\n",
    "\n",
    "사양의 엔드포인트에는 다음에 대한 작업이 포함됩니다:\n",
    "\n",
    "- 모든 이벤트 나열\n",
    "- 새 이벤트 생성\n",
    "- ID로 이벤트 검색\n",
    "- ID로 이벤트 삭제\n",
    "- ID로 이벤트 이름 업데이트하기\n",
    "\n",
    "스펙의 각 연산에는 'operationId'가 있으며, 이는 스펙을 함수 명세로 파싱할 때 함수 이름으로 사용됩니다. 사양에는 각 연산에 대한 매개변수의 데이터 유형과 구조를 정의하는 스키마도 포함되어 있습니다.\n",
    "\n",
    "스키마는 여기에서 확인할 수 있습니다:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "cell_id": "176efbfea4b546d28d9d9966342f286a",
    "deepnote_cell_type": "code",
    "deepnote_to_be_reexecuted": false,
    "execution_millis": 231,
    "execution_start": 1697419710160,
    "source_hash": "1ce3848"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'openapi': '3.0.0',\n",
       " 'info': {'version': '1.0.0',\n",
       "  'title': 'Event Management API',\n",
       "  'description': 'An API for managing event data'},\n",
       " 'paths': {'/events': {'get': {'summary': 'List all events',\n",
       "    'operationId': 'listEvents',\n",
       "    'responses': {'200': {'description': 'A list of events',\n",
       "      'content': {'application/json': {'schema': {'type': 'array',\n",
       "         'items': {'type': 'object',\n",
       "          'properties': {'id': {'type': 'string'},\n",
       "           'name': {'type': 'string'},\n",
       "           'date': {'type': 'string', 'format': 'date-time'},\n",
       "           'location': {'type': 'string'}},\n",
       "          'required': ['name', 'date', 'location']}}}}}}},\n",
       "   'post': {'summary': 'Create a new event',\n",
       "    'operationId': 'createEvent',\n",
       "    'requestBody': {'required': True,\n",
       "     'content': {'application/json': {'schema': {'type': 'object',\n",
       "        'properties': {'id': {'type': 'string'},\n",
       "         'name': {'type': 'string'},\n",
       "         'date': {'type': 'string', 'format': 'date-time'},\n",
       "         'location': {'type': 'string'}},\n",
       "        'required': ['name', 'date', 'location']}}}},\n",
       "    'responses': {'201': {'description': 'The event was created',\n",
       "      'content': {'application/json': {'schema': {'type': 'object',\n",
       "         'properties': {'id': {'type': 'string'},\n",
       "          'name': {'type': 'string'},\n",
       "          'date': {'type': 'string', 'format': 'date-time'},\n",
       "          'location': {'type': 'string'}},\n",
       "         'required': ['name', 'date', 'location']}}}}}}},\n",
       "  '/events/{id}': {'get': {'summary': 'Retrieve an event by ID',\n",
       "    'operationId': 'getEventById',\n",
       "    'parameters': [{'name': 'id',\n",
       "      'in': 'path',\n",
       "      'required': True,\n",
       "      'schema': {'type': 'string'}}],\n",
       "    'responses': {'200': {'description': 'The event',\n",
       "      'content': {'application/json': {'schema': {'type': 'object',\n",
       "         'properties': {'id': {'type': 'string'},\n",
       "          'name': {'type': 'string'},\n",
       "          'date': {'type': 'string', 'format': 'date-time'},\n",
       "          'location': {'type': 'string'}},\n",
       "         'required': ['name', 'date', 'location']}}}}}},\n",
       "   'delete': {'summary': 'Delete an event by ID',\n",
       "    'operationId': 'deleteEvent',\n",
       "    'parameters': [{'name': 'id',\n",
       "      'in': 'path',\n",
       "      'required': True,\n",
       "      'schema': {'type': 'string'}}],\n",
       "    'responses': {'204': {'description': 'The event was deleted'}}},\n",
       "   'patch': {'summary': \"Update an event's details by ID\",\n",
       "    'operationId': 'updateEventDetails',\n",
       "    'parameters': [{'name': 'id',\n",
       "      'in': 'path',\n",
       "      'required': True,\n",
       "      'schema': {'type': 'string'}}],\n",
       "    'requestBody': {'required': True,\n",
       "     'content': {'application/json': {'schema': {'type': 'object',\n",
       "        'properties': {'name': {'type': 'string'},\n",
       "         'date': {'type': 'string', 'format': 'date-time'},\n",
       "         'location': {'type': 'string'}},\n",
       "        'required': ['name', 'date', 'location']}}}},\n",
       "    'responses': {'200': {'description': \"The event's details were updated\",\n",
       "      'content': {'application/json': {'schema': {'type': 'object',\n",
       "         'properties': {'id': {'type': 'string'},\n",
       "          'name': {'type': 'string'},\n",
       "          'date': {'type': 'string', 'format': 'date-time'},\n",
       "          'location': {'type': 'string'}},\n",
       "         'required': ['name', 'date', 'location']}}}}}}}},\n",
       " 'components': {'schemas': {'Event': {'type': 'object',\n",
       "    'properties': {'id': {'type': 'string'},\n",
       "     'name': {'type': 'string'},\n",
       "     'date': {'type': 'string', 'format': 'date-time'},\n",
       "     'location': {'type': 'string'}},\n",
       "    'required': ['name', 'date', 'location']}}}}"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "with open('./data/example_events_openapi.json', 'r') as f:\n",
    "    openapi_spec = jsonref.loads(f.read()) # it's important to load with jsonref, as explained below\n",
    "\n",
    "display(openapi_spec)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "e3e39ad4ac854299bf62b5f7bb1bef45",
    "deepnote_cell_type": "text-cell-p",
    "formattedRanges": []
   },
   "source": [
    "이제 OpenAPI 사양을 잘 이해했으므로 이를 함수 사양으로 파싱할 수 있습니다.\n",
    "\n",
    "간단한 `openapi_to_functions` 함수를 작성하여 정의 목록을 생성할 수 있으며, 각 함수는 다음 키를 포함하는 사전으로 표현됩니다:\n",
    "\n",
    "- 이름`: 이것은 OpenAPI 사양에 정의된 API 엔드포인트의 작업 식별자에 해당합니다.\n",
    "- 설명`: 함수에 대한 간략한 설명 또는 요약으로, 함수가 수행하는 작업에 대한 개요를 제공합니다.\n",
    "- 매개변수`: 함수에 대해 예상되는 입력 매개변수를 정의하는 스키마입니다. 각 매개변수의 유형, 필수 또는 선택 여부 및 기타 관련 세부 정보에 대한 정보를 제공합니다.\n",
    "\n",
    "스키마에 정의된 각 엔드포인트에 대해 다음을 수행해야 합니다:\n",
    "\n",
    "1. **JSON 참조 확인**: OpenAPI 사양에서는 중복을 피하기 위해 JSON 참조($ref라고도 함)를 사용하는 것이 일반적입니다. 이러한 참조는 여러 위치에서 사용되는 정의를 가리킵니다. 예를 들어, 여러 API 엔드포인트가 동일한 객체 구조를 반환하는 경우 해당 구조를 한 번 정의한 다음 필요한 곳에서 참조할 수 있습니다. 이러한 참조를 해결하고 참조가 가리키는 콘텐츠로 대체해야 합니다.\n",
    "\n",
    "2. **함수 이름 추출하기:** 함수 이름으로 operationId를 간단히 사용하겠습니다. 또는 엔드포인트 경로와 작업을 함수 이름으로 사용할 수도 있습니다.\n",
    "\n",
    "3. **설명 및 매개변수 추출하기:** `description`, `summary`, `requestBody`, `parameters` 필드를 반복하여 함수의 설명과 매개변수를 채웁니다.\n",
    "\n",
    "구현은 다음과 같습니다:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "cell_id": "adbb17ca8a2a4fa2aa3f0213a0e211b6",
    "deepnote_cell_type": "code",
    "deepnote_to_be_reexecuted": false,
    "execution_millis": 333,
    "execution_start": 1697419853135,
    "source_hash": "ad112cb1"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'name': 'listEvents',\n",
      " 'description': 'List all events',\n",
      " 'parameters': {'type': 'object', 'properties': {}}}\n",
      "\n",
      "{'name': 'createEvent',\n",
      " 'description': 'Create a new event',\n",
      " 'parameters': {'type': 'object',\n",
      "                'properties': {'requestBody': {'type': 'object',\n",
      "                                               'properties': {'id': {'type': 'string'},\n",
      "                                                              'name': {'type': 'string'},\n",
      "                                                              'date': {'type': 'string',\n",
      "                                                                       'format': 'date-time'},\n",
      "                                                              'location': {'type': 'string'}},\n",
      "                                               'required': ['name',\n",
      "                                                            'date',\n",
      "                                                            'location']}}}}\n",
      "\n",
      "{'name': 'getEventById',\n",
      " 'description': 'Retrieve an event by ID',\n",
      " 'parameters': {'type': 'object',\n",
      "                'properties': {'parameters': {'type': 'object',\n",
      "                                              'properties': {'id': {'type': 'string'}}}}}}\n",
      "\n",
      "{'name': 'deleteEvent',\n",
      " 'description': 'Delete an event by ID',\n",
      " 'parameters': {'type': 'object',\n",
      "                'properties': {'parameters': {'type': 'object',\n",
      "                                              'properties': {'id': {'type': 'string'}}}}}}\n",
      "\n",
      "{'name': 'updateEventDetails',\n",
      " 'description': \"Update an event's details by ID\",\n",
      " 'parameters': {'type': 'object',\n",
      "                'properties': {'requestBody': {'type': 'object',\n",
      "                                               'properties': {'name': {'type': 'string'},\n",
      "                                                              'date': {'type': 'string',\n",
      "                                                                       'format': 'date-time'},\n",
      "                                                              'location': {'type': 'string'}},\n",
      "                                               'required': ['name',\n",
      "                                                            'date',\n",
      "                                                            'location']},\n",
      "                               'parameters': {'type': 'object',\n",
      "                                              'properties': {'id': {'type': 'string'}}}}}}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "def openapi_to_functions(openapi_spec):\n",
    "    functions = []\n",
    "\n",
    "    for path, methods in openapi_spec[\"paths\"].items():\n",
    "        for method, spec_with_ref in methods.items():\n",
    "            # 1. Resolve JSON references.\n",
    "            spec = jsonref.replace_refs(spec_with_ref)\n",
    "\n",
    "            # 2. Extract a name for the functions.\n",
    "            function_name = spec.get(\"operationId\")\n",
    "\n",
    "            # 3. Extract a description and parameters.\n",
    "            desc = spec.get(\"description\") or spec.get(\"summary\", \"\")\n",
    "\n",
    "            schema = {\"type\": \"object\", \"properties\": {}}\n",
    "\n",
    "            req_body = (\n",
    "                spec.get(\"requestBody\", {})\n",
    "                .get(\"content\", {})\n",
    "                .get(\"application/json\", {})\n",
    "                .get(\"schema\")\n",
    "            )\n",
    "            if req_body:\n",
    "                schema[\"properties\"][\"requestBody\"] = req_body\n",
    "\n",
    "            params = spec.get(\"parameters\", [])\n",
    "            if params:\n",
    "                param_properties = {\n",
    "                    param[\"name\"]: param[\"schema\"]\n",
    "                    for param in params\n",
    "                    if \"schema\" in param\n",
    "                }\n",
    "                schema[\"properties\"][\"parameters\"] = {\n",
    "                    \"type\": \"object\",\n",
    "                    \"properties\": param_properties,\n",
    "                }\n",
    "\n",
    "            functions.append(\n",
    "                {\"name\": function_name, \"description\": desc, \"parameters\": schema}\n",
    "            )\n",
    "\n",
    "    return functions\n",
    "\n",
    "\n",
    "functions = openapi_to_functions(openapi_spec)\n",
    "\n",
    "for function in functions:\n",
    "    pp(function)\n",
    "    print()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "f03f1aacdade4ed9a422797d3cf79fbb",
    "deepnote_cell_type": "text-cell-h2",
    "formattedRanges": []
   },
   "source": [
    "## GPT로 이러한 함수를 호출하는 방법\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "cell_id": "08712696b5fd4cafac7b4b496ee67c5a",
    "deepnote_cell_type": "text-cell-p",
    "formattedRanges": []
   },
   "source": [
    "이제 이러한 함수 정의가 있으므로 GPT를 활용하여 사용자 입력에 따라 지능적으로 함수를 호출할 수 있습니다.\n",
    "\n",
    "채팅 완료 API는 함수를 실행하는 것이 아니라 자체 코드에서 함수를 호출하는 데 사용할 수 있는 JSON을 생성한다는 점에 유의해야 합니다.\n",
    "\n",
    "함수 호출에 대한 자세한 내용은 전용 [함수 호출 가이드](./How_to_call_functions_with_chat_models.ipynb)를 참조하세요.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "cell_id": "b8f7d0f157264694b958008f93aabf3f",
    "deepnote_cell_type": "code",
    "deepnote_to_be_reexecuted": false,
    "execution_millis": 6442,
    "execution_start": 1697419907347,
    "source_hash": "ac9ad493"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      " >> Function call #: 1\n",
      "\n",
      "{'name': 'listEvents',\n",
      " 'arguments': '{}'}\n",
      "\n",
      " >> Function call #: 2\n",
      "\n",
      "{'name': 'createEvent',\n",
      " 'arguments': '{\\n'\n",
      "              '  \"requestBody\": {\\n'\n",
      "              '    \"id\": \"1234\",\\n'\n",
      "              '    \"name\": \"AGI Party\",\\n'\n",
      "              '    \"date\": \"2022-12-31\",\\n'\n",
      "              '    \"location\": \"New York\"\\n'\n",
      "              '  }\\n'\n",
      "              '}'}\n",
      "\n",
      " >> Function call #: 3\n",
      "\n",
      "{'name': 'deleteEvent',\n",
      " 'arguments': '{\\n  \"parameters\": {\\n    \"id\": \"2456\"\\n  }\\n}'}\n",
      "\n",
      ">> Message:\n",
      "\n",
      "Actions summary:\n",
      "1. Retrieved all the events successfully.\n",
      "2. Created a new event named \"AGI Party\" with ID 1234, scheduled for December 31, 2022, in New York.\n",
      "3. Deleted the event with ID 2456.\n"
     ]
    }
   ],
   "source": [
    "SYSTEM_MESSAGE = \"\"\"\n",
    "You are a helpful assistant. \n",
    "Respond to the following prompt by using function_call and then summarize actions. \n",
    "Ask for clarification if a user request is ambiguous.\n",
    "\"\"\"\n",
    "\n",
    "# Maximum number of function calls allowed to prevent infinite or lengthy loops\n",
    "MAX_CALLS = 5\n",
    "\n",
    "\n",
    "def get_openai_response(functions, messages):\n",
    "    return openai.ChatCompletion.create(\n",
    "        model=\"gpt-3.5-turbo-16k-0613\",\n",
    "        functions=functions,\n",
    "        function_call=\"auto\",  # \"auto\" means the model can pick between generating a message or calling a function.\n",
    "        temperature=0,\n",
    "        messages=messages,\n",
    "    )\n",
    "\n",
    "\n",
    "def process_user_instruction(functions, instruction):\n",
    "    num_calls = 0\n",
    "    messages = [\n",
    "        {\"content\": SYSTEM_MESSAGE, \"role\": \"system\"},\n",
    "        {\"content\": instruction, \"role\": \"user\"},\n",
    "    ]\n",
    "\n",
    "    while num_calls < MAX_CALLS:\n",
    "        response = get_openai_response(functions, messages)\n",
    "        message = response[\"choices\"][0][\"message\"]\n",
    "\n",
    "        if message.get(\"function_call\"):\n",
    "            print(f\"\\n>> Function call #: {num_calls + 1}\\n\")\n",
    "            pp(message[\"function_call\"])\n",
    "            messages.append(message)\n",
    "\n",
    "            # For the sake of this example, we'll simply add a message to simulate success.\n",
    "            # Normally, you'd want to call the function here, and append the results to messages.\n",
    "            messages.append(\n",
    "                {\n",
    "                    \"role\": \"function\",\n",
    "                    \"content\": \"success\",\n",
    "                    \"name\": message[\"function_call\"][\"name\"],\n",
    "                }\n",
    "            )\n",
    "\n",
    "            num_calls += 1\n",
    "        else:\n",
    "            print(\"\\n>> Message:\\n\")\n",
    "            print(message[\"content\"])\n",
    "            break\n",
    "\n",
    "    if num_calls >= MAX_CALLS:\n",
    "        print(f\"Reached max chained function calls: {MAX_CALLS}\")\n",
    "\n",
    "\n",
    "USER_INSTRUCTION = \"\"\"\n",
    "Instruction: Get all the events. \n",
    "Then create a new event named AGI Party.\n",
    "Then delete event with id 2456.\n",
    "\"\"\"\n",
    "\n",
    "process_user_instruction(functions, USER_INSTRUCTION)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "결론 ### 결론\n",
    "\n",
    "지금까지 OpenAPI 사양을 함수 사양으로 변환하여 GPT가 이를 지능적으로 호출할 수 있도록 하는 방법과 이를 서로 연결하여 복잡한 연산을 수행하는 방법을 보여드렸습니다.\n",
    "\n",
    "이 시스템의 가능한 확장에는 조건부 로직이나 루핑이 필요한 더 복잡한 사용자 지시를 처리하고, 실제 API와 통합하여 실제 연산을 수행하고, 오류 처리 및 유효성 검사를 개선하여 지시가 실행 가능하고 함수 호출이 성공하도록 하는 것이 포함될 수 있습니다.\n"
   ]
  }
 ],
 "metadata": {
  "deepnote": {},
  "deepnote_execution_queue": [],
  "deepnote_notebook_id": "84d101406ec34e36a9cf96d0c0c25a7d",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}