Apply review feedback to update cookbook

ahnjj · ahnjj · commit bc585c873aa4 · 2025-10-16T13:44:10.000Z
diff --git a/notebooks/ko/_toctree.yml b/notebooks/ko/_toctree.yml
@@ -28,7 +28,7 @@
         - local: multiagent_web_assistant
           title: 다중 에이전트 계층 구조에서 여러 에이전트가 협업하도록 하기
         - local: vector_search_agent
-          title: 벡터 검색 에이전트-허깅페이스 허브를 백엔드로 하는 똑똑한 검색 엔진
+          title: 벡터 검색 에이전트-허깅페이스 허브를 백엔드로 하는 지능형 검색 엔진
     - title: Multimodal 레시피
       isExpanded: false
       sections:
diff --git a/notebooks/ko/index.md b/notebooks/ko/index.md
@@ -16,7 +16,7 @@
 - [개인용 GPU에서 TRL로 SmolVLM DPO 파인튜닝하기](ko_fine_tuning_vlm_dpo_smolvlm_instruct)
 - [커스텀 데이터셋으로 객체 탐지 모델 파인튜닝하기, Spaces에 배포하기, 그리고 Gradio API 연동하기](fine_tuning_detr_custom_dataset)
 - [허깅페이스 허브를 백엔드로 사용한 벡터 검색](vector_search_with_hub_as_backend)
-- [벡터 검색 에이전트-허깅페이스 허브를 백엔드로 하는 똑똑한 검색 엔진](vector_search_agent)
+- [벡터 검색 에이전트-허깅페이스 허브를 백엔드로 하는 지능형 검색 엔진](vector_search_agent)
 
 더 다양한 노트북을 확인하고 싶다면 Cookbook's [GitHub 리포지토리](https://github.com/huggingface/cookbook)에 방문해보세요.
 
diff --git a/notebooks/ko/vector_search_agent.ipynb b/notebooks/ko/vector_search_agent.ipynb
@@ -6,21 +6,22 @@
         "id": "ksUdu7H7qBig"
       },
       "source": [
-        "# 🤖 벡터 검색 에이전트: 허깅페이스 허브를 백엔드로 하는 똑똑한 검색 엔진\n",
+        "# 🤖 벡터 검색 에이전트: 허깅페이스 허브를 백엔드로 하는 지능형 검색 엔진\n",
         "\n",
         "_참조: [Martin Elstner](https://github.com/MartinEls)\n",
         "_작성자: [안정](https://github.com/ahnjj)\n",
         "\n",
-        "검색엔진은 크게 키워드 검색과 벡터 검색으로 분류 됩니다. 키워드 검색과는 달리, 벡터 검색으로 진행할 경우 두가지를 고려해야합니다.\n",
+        "검색 엔진은 크게 키워드 검색과 벡터 검색으로 나눌 수 있습니다.\n",
+        "키워드 검색과 달리, 벡터 검색을 사용할 때는 두 가지를 고려해야 합니다.\n",
         "1. 적합한 임베딩 모델로 데이터셋과 쿼리를 임베딩하는 작업\n",
         "2. 임베딩 데이터를 처리할 수 있는 DB\n",
         "\n",
-        "그러나, 임베딩값을 기반으로하는 벡터 검색만으로는 '사용자가 원하는 답변'를 보장하기 어렵습니다.\n",
+        "하지만 임베딩 값을 기반으로 한 벡터 검색만으로는 ‘사용자가 원하는 답변’을 보장하기 어렵습니다.\n",
         "\n",
-        "따라서 검색의 각 단계에서 에이전트가 각 단계를 자율적으로 판단하고 최적화한다면 사용자가 원하는 답변에 가까운 검색 결과를 얻을 수 있을 것 같습니다!\n",
+        "그래서 검색 과정에서 에이전트가 자율적으로 판단하고 최적화한다면, 사용자 의도에 더 가까운 검색 결과를 얻을 수 있습니다.\n",
         "\n",
         "### Agentic 접근 방식의 차별점\n",
-        "기존 벡터검색 워크플로우\n",
+        "기존 벡터 검색 워크플로우\n",
         "```\n",
         "데이터 ➡ 데이터 임베딩(고정 모델) ➡ 인덱스 생성 ➡ 사용자 질의 ➡ 유사도 검색 ➡ 답변\n",
         "```\n",
@@ -30,24 +31,45 @@
         "```\n",
         "\n",
         "### DuckDB?\n",
-        "허깅페이스의 데이터셋은 파켓(parquet) 파일에 의존하는데 빠른 인메모리 데이터베이스 시스템인 [DuckDB를 사용하면 이 파일들과 상호작용](https://huggingface.co/docs/hub/en/datasets-duckdb)할 수 있습니다. 또한 DuckDB의 기능 중 하나는 [벡터 유사도 검색](https://duckdb.org/docs/extensions/vss.html)으로, 인덱스 유무에 관계없이 사용할 수 있습니다.\n",
+        "허깅페이스의 데이터셋은 파켓(parquet) 파일을 기반으로 동작하는데, 이때 빠른 인메모리 데이터베이스 시스템인 [DuckDB를 사용하면 이 파일들과 상호작용](https://huggingface.co/docs/hub/en/datasets-duckdb)할 수 있습니다. 또한 DuckDB의 기능 중 하나는 [벡터 유사도 검색](https://duckdb.org/docs/extensions/vss.html)으로, 인덱스 유무에 관계없이 사용할 수 있습니다.\n",
         "\n",
         "\n",
         "이번 노트북에서는 단일 Agent에 여러가지 도구를 주어 수행하는 간단한 Agentic 벡터 검색 엔진을 만들어 보겠습니다."
       ]
     },
     {
       "cell_type": "markdown",
-      "metadata": {
-        "id": "Old2t6dnpi3M"
-      },
+      "metadata": {},
       "source": [
-        "# 도구정의\n",
-        "정의할 도구는 아래와 같습니다.\n",
-        "- 임베딩 생성 도구\n",
-        "- 인덱스 생성 도구\n",
-        "- 유사도 검색 도구\n",
-        "- 답변 생성 도구"
+        "필요한 의존성을 설치합니다 :"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# 본 예제 파일은 Python 3.10 이상 버전에서만 실행할 수 있습니다.\n",
+        "!pip install -U smolagents datasets sentence-transformers duckdb openai"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "HuggingFace의 추론 API를 사용하기 위해 로그인합니다 : "
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from huggingface_hub import notebook_login\n",
+        "\n",
+        "notebook_login()"
       ]
     },
     {
@@ -60,9 +82,24 @@
       "source": [
         "from smolagents import tool\n",
         "from datasets import Dataset\n",
-        "from sentence_transformers import SentenceTransformer\n",
-        "import duckdb\n",
-        "import openai"
+        "import os\n",
+        "\n",
+        "# 도구 사용을 위해 OPENAI 키를 발급 받아야합니다.\n",
+        "os.environ[\"OPENAI_API_KEY\"] = \"YOUR KEY\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "Old2t6dnpi3M"
+      },
+      "source": [
+        "# 도구 정의\n",
+        "정의할 도구는 아래와 같습니다.\n",
+        "- 임베딩 생성 도구\n",
+        "- 인덱스 생성 도구\n",
+        "- 유사도 검색 도구\n",
+        "- 답변 생성 도구"
       ]
     },
     {
@@ -72,7 +109,7 @@
       },
       "source": [
         "### 도구1 : 임베딩 생성\n",
-        "일반적으로, 임베딩 작업에서는 더 작은 배치사이즈로 줄여 청킹하나 여기서는 데이터셋을 임베딩으로 바꾸기만 하겠습니다."
+        "일반적으로, 임베딩 작업에서는 작은 배치 사이즈로 데이터를 청킹하지만 여기서는 단순히 데이터셋을 임베딩으로 변환하는 과정만 수행하겠습니다."
       ]
     },
     {
@@ -95,11 +132,12 @@
         "    Args:\n",
         "        dataset: 임베딩을 생성할 대상 데이터셋\n",
         "        model_id: 임베딩에 사용할 모델\n",
-        "        column_name: 임베딩할 컬럼 이름\n",
+        "        column_name: 임베딩할 열 이름\n",
         "\n",
         "    Returns:\n",
         "        임베딩이 추가된 데이터셋\n",
         "  \"\"\"\n",
+        "  from sentence_transformers import SentenceTransformer\n",
         "\n",
         "  model = SentenceTransformer(model_id)\n",
         "\n",
@@ -144,7 +182,7 @@
         "id": "kS61lIgSAYmS"
       },
       "source": [
-        "### 도구2 : DuckDB인덱스 만들기"
+        "### 도구2 : DuckDB 인덱스 만들기"
       ]
     },
     {
@@ -167,11 +205,13 @@
         "    Args:\n",
         "        dataset_with_embeddings: 이미 임베딩이 포함된 데이터셋\n",
         "        table_name: 생성할 테이블 이름\n",
-        "        embedding_column: 임베딩 컬럼 이름\n",
+        "        embedding_column: 임베딩 열 이름\n",
         "\n",
         "    Returns:\n",
         "        None\n",
         "    \"\"\"\n",
+        "    import duckdb\n",
+        "    \n",
         "    # VSS 확장 설치 및 로드\n",
         "    duckdb.sql(\"INSTALL vss; LOAD vss;\")\n",
         "    duckdb.sql(f\"DROP TABLE IF EXISTS {table_name};\")\n",
@@ -218,7 +258,7 @@
         "id": "ygW649Ln0OvV"
       },
       "source": [
-        "### 도구3: 벡터 검색 수행하기"
+        "### 도구3 : 벡터 검색 수행하기"
       ]
     },
     {
@@ -251,6 +291,8 @@
         "        dict: 검색 결과\n",
         "    \"\"\"\n",
         "    from sentence_transformers import SentenceTransformer\n",
+        "    import duckdb\n",
+        "    \n",
         "    model = SentenceTransformer(model_id)\n",
         "    embedding = model.encode(query).tolist()\n",
         "    return duckdb.sql(\n",
@@ -269,7 +311,7 @@
         "id": "XVT4VYknqBij"
       },
       "source": [
-        "무거운 벡터 검색 엔진을 배포할 필요가 없고 저장소는 허브에서 처리됩니다."
+        "무거운 벡터 검색 엔진을 따로 배포할 필요 없고, 저장소는 허브에서 처리됩니다."
       ]
     },
     {
@@ -278,7 +320,7 @@
         "id": "AQf6IxFGqBij"
       },
       "source": [
-        "### 도구4 :답변 생성 도구\n",
+        "### 도구4 : 답변 생성 도구\n",
         "유사도 검색 결과 청크를 기반으로, LLM이 사용자가 원할 만한 답변을 생성합니다."
       ]
     },
@@ -302,6 +344,8 @@
         "    Returns:\n",
         "        str: 생성된 답변\n",
         "    \"\"\"\n",
+        "    import openai   # OPENAI 키 발급이 필요합니다.\n",
+        "    \n",
         "    context = \"\\n\\n\".join(chunks)\n",
         "    prompt = f\"Context:\\n{context}\\n\\nQuestion: {query}\\nAnswer:\"\n",
         "    response = openai.ChatCompletion.create(\n",
@@ -523,7 +567,7 @@
         "\n",
         "단순히 검색 결과만을 가져오는 것이 아니라, 검색결과를 바탕으로 쿼리에 따른 답변을 정제해서 보여주었습니다.✌🏻\n",
         "\n",
-        "위는 간단한 에이전트 시스템이지만, 품질 평가, 분석 등을 추가한다면 진정한 Agentic 검색 엔진을 구현할 수 있을 것 입니다!"
+        "지금까지 간단한 에이전트 시스템을 만들어보았습니다. 여기에 품질 평가, 분석 등을 추가한다면 진정한 Agentic 검색 엔진을 구현할 수 있습니다."
       ]
     }
   ],
