@intlayer/docs 5.8.1-canary.0 → 6.0.0-canary.0

package/blog/ja/rag_powered_documentation_assistant.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: RAG搭載ドキュメントアシスタントの構築（チャンク分割、埋め込み、検索）
+description: RAG搭載ドキュメントアシスタントの構築（チャンク分割、埋め込み、検索）
+keywords:
+  - RAG
+  - ドキュメント
+  - アシスタント
+  - チャンク分割
+  - 埋め込み
+  - 検索
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# RAG搭載ドキュメントアシスタントの構築（チャンク分割、埋め込み、検索）
+
+## 得られるもの
+
+私はRAG搭載のドキュメントアシスタントを構築し、すぐに使えるボイラープレートとしてパッケージ化しました。
+
+- すぐに使えるアプリケーション（Next.js + OpenAI API）付き
+- 動作するRAGパイプライン（チャンク分割、埋め込み、コサイン類似度）を含む
+- Reactで構築された完全なチャットボットUIを提供
+- すべてのUIコンポーネントはTailwind CSSで完全に編集可能
+- すべてのユーザークエリをログに記録し、欠落しているドキュメント、ユーザーの問題点、製品の機会を特定するのに役立てる
+
+👉 [ライブデモ](https://intlayer.org/doc/why) 👉 [コードボイラープレート](https://github.com/aymericzip/smart_doc_RAG)
+
+## はじめに
+
+ドキュメントの中で迷子になり、答えを探して延々とスクロールしたことがあるなら、その苦痛はよくわかるでしょう。ドキュメントは役に立ちますが、静的であり、検索も使いづらいことが多いです。
+
+そこで登場するのが**RAG（Retrieval-Augmented Generation、検索強化生成）**です。ユーザーにテキストを掘り下げさせる代わりに、**検索**（ドキュメントの適切な部分を見つける）と**生成**（LLMが自然に説明する）を組み合わせることができます。
+
+この投稿では、私がどのようにしてRAG搭載のドキュメントチャットボットを構築したか、そしてそれがユーザーがより速く答えを見つけるのを助けるだけでなく、プロダクトチームがユーザーの課題を理解する新しい方法を提供するかを説明します。
+
+## なぜドキュメントにRAGを使うのか？
+
+RAGが人気のアプローチになったのには理由があります。それは、大規模言語モデルを実際に役立てる最も実用的な方法の一つだからです。
+
+ドキュメントにおける利点は明確です：
+
+- 即時回答：ユーザーは自然言語で質問し、関連する回答を得られます。
+- より良いコンテキスト：モデルは最も関連性の高いドキュメントの部分だけを参照するため、幻覚（誤情報）が減ります。
+- 人間らしい検索体験：Algolia + FAQ + チャットボットを一つにまとめたような感覚です。
+- フィードバックループ：クエリを保存することで、ユーザーが本当に困っていることを明らかにします。
+
+その最後のポイントは非常に重要です。RAGシステムは単に質問に答えるだけでなく、人々が何を尋ねているのかを教えてくれます。つまり：
+
+- ドキュメントに不足している情報を発見できます。
+- 新たな機能リクエストが浮かび上がってきます。
+- 製品戦略を導くパターンを見つけることもできます。
+
+ですから、RAGは単なるサポートツールではありません。**プロダクト発見エンジン**でもあるのです。
+
+## RAGパイプラインの仕組み
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+大まかに言うと、私が使ったレシピは以下の通りです：
+
+1.  **ドキュメントのチャンク分割** 大きなMarkdownファイルをチャンクに分割します。チャンク分割により、ドキュメントの関連部分だけをコンテキストとして提供できます。
+2.  **埋め込みの生成** 各チャンクをOpenAIの埋め込みAPI（text-embedding-3-large）やベクターデータベース（Chroma、Qdrant、Pinecone）を使ってベクトルに変換します。
+3.  **インデックス作成と保存** 埋め込みはシンプルなJSONファイルに保存されます（デモ用）が、本番環境ではベクターデータベースを使用することが多いでしょう。
+4.  **検索（RAGのR）** ユーザーのクエリを埋め込み、コサイン類似度を計算し、最もマッチするチャンクを取得します。
+5.  **拡張と生成（RAGのAG）** 取得したチャンクをChatGPTのプロンプトに注入し、モデルが実際のドキュメントの文脈を踏まえて回答します。
+6.  **フィードバックのためのクエリのログ記録** すべてのユーザークエリを保存します。これは問題点の把握、ドキュメントの不足、新たな機会の発見に非常に役立ちます。
+
+## ステップ1: ドキュメントの読み込み
+
+最初のステップはシンプルでした：docs/フォルダ内のすべての.mdファイルをスキャンする方法が必要でした。Node.jsとglobを使って、各Markdownファイルの内容をメモリに取得しました。
+
+これによりパイプラインは柔軟になります。Markdownの代わりに、データベースやCMS、さらにはAPIからドキュメントを取得することも可能です。
+
+## ステップ 2: ドキュメントのチャンク分割
+
+なぜチャンク分割をするのか？それは言語モデルには**コンテキストの制限**があるからです。ドキュメント全体を一度に与えることはできません。
+
+そこで、テキストを扱いやすいチャンク（例：各500トークン）に分割し、重複部分（例：100トークン）を設けます。重複部分は連続性を保ち、チャンクの境界で意味が失われないようにします。
+
+**例：**
+
+- チャンク1 → 「…多くの人が忘れていた古い図書館。そのそびえ立つ棚は本でいっぱいだった…」
+- チャンク2 → 「…棚はあらゆるジャンルの本で満たされており、それぞれが物語をささやいていた…」
+
+重複部分により、両方のチャンクが共通のコンテキストを含むため、検索時の一貫性が保たれます。
+
+このトレードオフ（チャンクサイズとオーバーラップのバランス）は、RAGの効率性にとって重要です：
+
+- 小さすぎると → ノイズが増えます。
+- 大きすぎると → コンテキストサイズが膨れ上がります。
+
+## ステップ3：埋め込みの生成
+
+ドキュメントをチャンクに分割したら、各チャンクを表す高次元ベクトルである**埋め込み**を生成します。
+
+私はOpenAIのtext-embedding-3-largeモデルを使用しましたが、任意の最新の埋め込みモデルを使うことができます。
+
+**埋め込みの例：**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elements
+];
+```
+
+各ベクトルはテキストの数学的な指紋であり、類似検索を可能にします。
+
+## ステップ4：埋め込みのインデックス作成と保存
+
+埋め込みを何度も再生成しないように、embeddings.jsonに保存しました。
+
+本番環境では、以下のようなベクトルデータベースを使用することが一般的です：
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS、Weaviate、Milvusなど
+
+ベクトルDBはインデックス作成、スケーラビリティ、高速検索を処理します。しかし、私のプロトタイプではローカルのJSONで十分でした。
+
+## ステップ5：コサイン類似度による検索
+
+ユーザーが質問をしたとき：
+
+1. クエリの埋め込みを生成する。
+2. すべてのドキュメント埋め込みと**コサイン類似度**で比較する。
+3. 最も類似度の高い上位N個のチャンクだけを保持する。
+
+コサイン類似度は2つのベクトル間の角度を測定します。完全一致は**1.0**のスコアです。
+
+この方法で、システムはクエリに最も近いドキュメントの部分を見つけます。
+
+## ステップ6：拡張＋生成
+
+ここで魔法が始まります。上位のチャンクを取り出し、それらをChatGPTの**システムプロンプト**に注入します。
+
+それは、モデルがまるでそれらのチャンクが会話の一部であるかのように回答することを意味します。
+
+結果：正確で、**ドキュメントに基づいた応答**。
+
+## ステップ7：ユーザークエリのログ記録
+
+これが隠れたスーパーパワーです。
+
+ユーザーが尋ねたすべての質問が保存されます。時間が経つにつれて、以下のようなデータセットが構築されます：
+
+- 最も頻繁に尋ねられる質問（FAQに最適）
+- 未回答の質問（ドキュメントが不足しているか不明瞭）
+- 質問に偽装された機能リクエスト（「Xと統合できますか？」など）
+- 予期していなかった新たなユースケース
+
+これにより、あなたのRAGアシスタントは**継続的なユーザーリサーチツール**に変わります。
+
+## コストはどのくらいかかるのか？
+
+RAGに対する一般的な反論の一つはコストですが、実際には驚くほど安価です：
+
+- 約200件のドキュメントの埋め込み生成は約**5分**で、費用は**1〜2ユーロ**程度です。
+- ドキュメント検索機能は100％無料です。
+- クエリには「thinking」モードなしで gpt-4o-latest を使用しています。Intlayer では、月に約 **300 件のチャットクエリ** があり、OpenAI API の請求額はめったに **10ドル** を超えません。
+
+その上に、ホスティングコストを含めることができます。
+
+## 実装の詳細
+
+スタック:
+
+- モノレポ: pnpm ワークスペース
+- ドキュメントパッケージ: Node.js / TypeScript / OpenAI API
+- フロントエンド: Next.js / React / Tailwind CSS
+- バックエンド: Node.js API ルート / OpenAI API
+
+`@smart-doc/docs` パッケージはドキュメント処理を担当する TypeScript パッケージです。Markdown ファイルが追加または変更されると、このパッケージには各言語のドキュメントリストを再構築し、埋め込みを生成し、それらを `embeddings.json` ファイルに保存する `build` スクリプトが含まれています。
+
+フロントエンドには、以下を提供する Next.js アプリケーションを使用しています:
+
+- MarkdownをHTMLにレンダリングする機能
+- 関連するドキュメントを検索するための検索バー
+- ドキュメントに関する質問を行うためのチャットボットインターフェース
+
+ドキュメント検索を実行するために、Next.jsアプリケーションにはAPIルートが含まれており、`@smart-doc/docs`パッケージの関数を呼び出してクエリに一致するドキュメントチャンクを取得します。これらのチャンクを使用して、ユーザーの検索に関連するドキュメントページのリストを返すことができます。
+
+チャットボット機能については、同じ検索プロセスを踏みますが、取得したドキュメントチャンクをChatGPTに送信するプロンプトに追加で注入します。
+
+以下はChatGPTに送信されるプロンプトの例です：
+
+システムプロンプト：
+
+```txt
+あなたはIntlayerのドキュメントに関する質問に答えることができる有用なアシスタントです。
+
+関連チャンク：
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/ja/getting-started"
+---
+
+# はじめに
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/ja/another-doc"
+---
+
+# 別のドキュメント
+
+...
+```
+
+ユーザーのクエリ：
+
+```txt
+はじめにどうすればいいですか？
+```
+
+APIルートからのレスポンスはSSEを使ってストリーミングします。
+
+前述の通り、"thinking"モードなしでgpt-4-turboを使用しています。応答は関連性が高く、レイテンシも低いです。
+gpt-5も試しましたが、レイテンシが高すぎました（返信に最大15秒かかることもありました）。しかし将来的に再検討する予定です。
+
+👉 [ここでデモを試す](https://intlayer.org/doc/why) 👉 [GitHubでコードテンプレートを確認](https://github.com/aymericzip/smart_doc_RAG)
+
+## さらに進むために
+
+このプロジェクトは最小限の実装です。しかし、以下のように多くの方法で拡張できます：
+
+- MCPサーバー → ドキュメント検索機能をMCPサーバーに移行し、ドキュメントをあらゆるAIアシスタントに接続可能にする
+
+- ベクターデータベース → 数百万のドキュメントチャンクにスケール可能
+- LangChain / LlamaIndex → RAGパイプライン用の既製フレームワーク
+- 分析ダッシュボード → ユーザーのクエリや問題点を可視化
+- マルチソース検索 → ドキュメントだけでなく、データベースのエントリ、ブログ投稿、チケットなども取得可能
+- 改良されたプロンプティング → 再ランキング、フィルタリング、ハイブリッド検索（キーワード＋セマンティック）
+
+## 直面した制限事項
+
+- チャンク分割と重複は経験則に基づく。適切なバランス（チャンクサイズ、重複率、取得チャンク数）は反復とテストが必要。
+- ドキュメントが変更されても埋め込みは自動再生成されない。システムは、保存されているチャンク数と異なる場合にのみファイルの埋め込みをリセットする。
+- このプロトタイプでは、埋め込みはJSONに保存されています。これはデモには適していますが、Gitを汚染します。本番環境では、データベースや専用のベクターストアの方が適しています。
+
+## ドキュメントを超えて重要な理由
+
+興味深いのは単なるチャットボットだけではありません。**フィードバックループ**です。
+
+RAGを使うと、単に答えるだけではなく：
+
+- ユーザーが何に混乱しているかを学びます。
+- 彼らがどの機能を期待しているかを発見します。
+- 実際のクエリに基づいて製品戦略を適応させます。
+
+**例：**
+
+新機能をリリースしてすぐに以下がわかると想像してください：
+
+- 質問の50％が同じ不明瞭なセットアップ手順に関するもの
+- ユーザーがまだサポートしていない統合を繰り返し求める
+- 新しいユースケースを示す用語で検索される
+
+それがユーザーから直接得られる**プロダクトインテリジェンス**です。
+
+## 結論
+
+RAGは、LLMを実用的にする最もシンプルで強力な方法の一つです。**検索（retrieval）＋生成（generation）**を組み合わせることで、静的なドキュメントを**スマートアシスタント**に変え、同時に継続的な製品インサイトの流れを得ることができます。
+
+私にとって、このプロジェクトはRAGが単なる技術的なトリックではないことを示しました。RAGはドキュメントを以下のように変革する方法です：
+
+- インタラクティブなサポートシステム
+- フィードバックチャネル
+- 製品戦略ツール
+
+👉 [ここでデモを試す](https://intlayer.org/doc/why) 👉 [GitHubでコードテンプレートを確認する](https://github.com/aymericzip/smart_doc_RAG)
+
+もしあなたもRAGを試しているなら、どのように使っているかぜひ教えてください。

package/blog/ko/rag_powered_documentation_assistant.md

@@ -0,0 +1,283 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: RAG 기반 문서 지원 도우미 구축하기 (청킹, 임베딩, 검색)
+description: RAG 기반 문서 지원 도우미 구축하기 (청킹, 임베딩, 검색)
+keywords:
+  - RAG
+  - 문서
+  - 도우미
+  - 청킹
+  - 임베딩
+  - 검색
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# RAG 기반 문서 지원 도우미 구축하기 (청킹, 임베딩, 검색)
+
+## 제공 내용
+
+저는 RAG 기반 문서 지원 도우미를 구축하고, 즉시 사용할 수 있는 보일러플레이트로 패키징했습니다.
+
+- 즉시 사용 가능한 애플리케이션 포함 (Next.js + OpenAI API)
+- 작동하는 RAG 파이프라인 포함 (청킹, 임베딩, 코사인 유사도)
+- React로 구축된 완전한 챗봇 UI 제공
+- 모든 UI 컴포넌트는 Tailwind CSS로 완전히 편집 가능합니다.
+- 모든 사용자 쿼리를 기록하여 누락된 문서, 사용자 불편 사항 및 제품 기회를 식별하는 데 도움을 줍니다.
+
+👉 [라이브 데모](https://intlayer.org/doc/why) 👉 [코드 보일러플레이트](https://github.com/aymericzip/smart_doc_RAG)
+
+## 소개
+
+문서에서 답을 찾으려고 끝없이 스크롤하다가 길을 잃은 적이 있다면, 그 고통이 얼마나 큰지 아실 겁니다. 문서는 유용하지만 정적이고, 검색하는 것이 종종 불편하게 느껴집니다.
+
+바로 이때 **RAG (검색 증강 생성, Retrieval-Augmented Generation)** 이 등장합니다. 사용자가 텍스트를 뒤지도록 강요하는 대신, **검색** (문서의 적절한 부분 찾기)과 **생성** (LLM이 자연스럽게 설명하기)을 결합할 수 있습니다.
+
+이 글에서는 제가 어떻게 RAG 기반 문서 챗봇을 만들었는지, 그리고 그것이 단순히 사용자가 더 빠르게 답을 찾도록 돕는 것뿐만 아니라 제품 팀이 사용자 고충을 이해하는 새로운 방법을 제공하는지 설명하겠습니다.
+
+## 왜 문서에 RAG를 사용할까?
+
+RAG가 인기 있는 접근법이 된 데는 이유가 있습니다. 대형 언어 모델을 실제로 유용하게 만드는 가장 실용적인 방법 중 하나이기 때문입니다.
+
+문서에 있어서 그 이점은 명확합니다:
+
+- 즉각적인 답변: 사용자가 자연어로 질문하면 관련된 답변을 받습니다.
+- 더 나은 맥락: 모델은 가장 관련성 높은 문서 부분만 보기 때문에 환각 현상이 줄어듭니다.
+- 인간적인 검색 경험: Algolia + FAQ + 챗봇이 하나로 합쳐진 느낌입니다.
+- 피드백 루프: 쿼리를 저장함으로써 사용자가 실제로 어려워하는 점을 파악할 수 있습니다.
+
+그 마지막 점이 매우 중요합니다. RAG 시스템은 단순히 질문에 답하는 것뿐만 아니라 사람들이 무엇을 묻고 있는지 알려줍니다. 이는 다음을 의미합니다:
+
+- 문서에서 누락된 정보를 발견할 수 있습니다.
+- 기능 요청이 나타나는 것을 볼 수 있습니다.
+- 제품 전략을 안내할 수 있는 패턴을 발견할 수 있습니다.
+
+따라서 RAG는 단순한 지원 도구가 아닙니다. 그것은 또한 **제품 발견 엔진**입니다.
+
+## RAG 파이프라인 작동 방식
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+전체적인 개요는 다음과 같습니다:
+
+1.  **문서 청킹(Chunking)** 큰 마크다운 파일을 여러 청크로 분할합니다. 청킹은 문서의 관련된 부분만 컨텍스트로 제공할 수 있게 합니다.
+2.  **임베딩 생성(Generating embeddings)** 각 청크는 OpenAI의 임베딩 API(text-embedding-3-large) 또는 벡터 데이터베이스(Chroma, Qdrant, Pinecone)를 사용해 벡터로 변환됩니다.
+3.  **인덱싱 및 저장** 임베딩은 간단한 JSON 파일에 저장됩니다(데모용). 하지만 실제 운영 환경에서는 벡터 DB를 사용할 가능성이 높습니다.
+4.  **검색 (RAG의 R)** 사용자 쿼리를 임베딩하고, 코사인 유사도를 계산하여 가장 일치하는 청크들을 검색합니다.
+5.  **증강 및 생성 (RAG의 AG)** 해당 청크들을 ChatGPT 프롬프트에 주입하여, 모델이 실제 문서 컨텍스트를 기반으로 답변하도록 합니다.
+6.  **피드백을 위한 쿼리 기록** 모든 사용자 쿼리를 저장합니다. 이는 문제점 파악, 누락된 문서, 새로운 기회를 이해하는 데 매우 중요합니다.
+
+## 1단계: 문서 읽기
+
+첫 번째 단계는 간단했습니다: docs/ 폴더 내 모든 .md 파일을 스캔할 방법이 필요했습니다. Node.js와 glob을 사용하여 각 마크다운 파일의 내용을 메모리로 가져왔습니다.
+
+이것은 파이프라인을 유연하게 유지합니다: Markdown 대신 데이터베이스, CMS, 또는 API에서 문서를 가져올 수도 있습니다.
+
+## 2단계: 문서 청킹(Chunking)
+
+왜 청킹을 할까요? 언어 모델에는 **컨텍스트 제한**이 있기 때문입니다. 전체 문서 책을 한 번에 입력하는 것은 불가능합니다.
+
+그래서 텍스트를 관리 가능한 청크(예: 각 500 토큰)로 나누고, 겹치는 부분(예: 100 토큰)을 둡니다. 겹치는 부분은 청크 경계에서 의미가 끊기지 않도록 연속성을 보장합니다.
+
+**예시:**
+
+- 청크 1 → “…많은 이들이 잊어버린 오래된 도서관. 그 높이 솟은 선반들은 책들로 가득 차 있었다…”
+- 청크 2 → “…선반들은 상상할 수 있는 모든 장르의 책들로 가득 차 있었고, 각각이 이야기를 속삭이고 있었다…”
+
+이 겹침은 두 청크가 공유된 컨텍스트를 포함하도록 하여, 검색 시 일관성을 유지하게 합니다.
+
+이 절충안(청크 크기 대 중첩)은 RAG 효율성에 매우 중요합니다:
+
+- 너무 작으면 → 노이즈가 발생합니다.
+- 너무 크면 → 컨텍스트 크기가 너무 커집니다.
+
+## 3단계: 임베딩 생성
+
+문서가 청크로 나뉘면, 각 청크를 나타내는 고차원 벡터인 **임베딩**을 생성합니다.
+
+저는 OpenAI의 text-embedding-3-large 모델을 사용했지만, 최신 임베딩 모델이라면 어떤 것이든 사용할 수 있습니다.
+
+**임베딩 예시:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elements
+];
+```
+
+각 벡터는 텍스트의 수학적 지문으로, 유사도 검색을 가능하게 합니다.
+
+## 4단계: 임베딩 인덱싱 및 저장
+
+임베딩을 여러 번 다시 생성하지 않도록, 저는 이를 embeddings.json에 저장했습니다.
+
+프로덕션 환경에서는 다음과 같은 벡터 데이터베이스를 사용하는 것이 좋습니다:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus 등
+
+벡터 DB는 인덱싱, 확장성, 빠른 검색을 처리합니다. 하지만 제 프로토타입에서는 로컬 JSON으로도 충분했습니다.
+
+## 5단계: 코사인 유사도를 이용한 검색
+
+사용자가 질문을 하면:
+
+1. 쿼리에 대한 임베딩을 생성합니다.
+2. 모든 문서 임베딩과 **코사인 유사도**를 사용해 비교합니다.
+3. 가장 유사한 상위 N개의 청크만 유지합니다.
+
+코사인 유사도는 두 벡터 사이의 각도를 측정합니다. 완벽한 일치는 **1.0** 점수를 받습니다.
+
+이렇게 시스템은 쿼리와 가장 가까운 문서 구간을 찾습니다.
+
+## 6단계: 증강 + 생성
+
+이제 마법이 시작됩니다. 상위 청크들을 가져와 ChatGPT의 **시스템 프롬프트**에 주입합니다.
+
+그것은 모델이 마치 해당 청크들이 대화의 일부인 것처럼 답변한다는 의미입니다.
+
+결과: 정확하고, **문서 기반의 응답**.
+
+## 7단계: 사용자 쿼리 기록
+
+이것이 숨겨진 슈퍼파워입니다.
+
+모든 질문이 저장됩니다. 시간이 지나면서 다음과 같은 데이터셋을 구축할 수 있습니다:
+
+- 가장 빈번한 질문들 (FAQ에 매우 유용)
+- 답변되지 않은 질문들 (문서가 없거나 불명확한 경우)
+- 질문으로 위장된 기능 요청 (“X와 통합되나요?”)
+- 예상치 못한 새로운 사용 사례
+
+이로써 당신의 RAG 어시스턴트는 **지속적인 사용자 조사 도구**가 됩니다.
+
+## 비용은 얼마나 들까?
+
+RAG에 대한 흔한 반대 의견 중 하나는 비용입니다. 실제로는 놀라울 정도로 저렴합니다:
+
+- 약 200개의 문서에 대한 임베딩 생성은 약 **5분**이 걸리며 비용은 **1~2 유로**입니다.
+- 문서 검색 기능은 100% 무료입니다.
+- 쿼리의 경우, “thinking” 모드 없이 gpt-4o-latest를 사용합니다. Intlayer에서는 한 달에 약 **300건의 채팅 쿼리**가 발생하며, OpenAI API 요금은 거의 **$10**를 넘지 않습니다.
+
+여기에 호스팅 비용을 포함할 수 있습니다.
+
+## 구현 세부사항
+
+스택:
+
+- 모노레포: pnpm 워크스페이스
+- 문서 패키지: Node.js / TypeScript / OpenAI API
+- 프론트엔드: Next.js / React / Tailwind CSS
+- 백엔드: Node.js API 라우트 / OpenAI API
+
+`@smart-doc/docs` 패키지는 문서 처리를 담당하는 TypeScript 패키지입니다. 마크다운 파일이 추가되거나 수정되면, 이 패키지는 각 언어별 문서 목록을 재구성하고 임베딩을 생성하여 `embeddings.json` 파일에 저장하는 `build` 스크립트를 포함합니다.
+
+프론트엔드에는 다음 기능을 제공하는 Next.js 애플리케이션을 사용합니다:
+
+- 마크다운을 HTML로 렌더링
+- 관련 문서를 찾기 위한 검색 바
+- 문서에 대한 질문을 할 수 있는 챗봇 인터페이스
+
+문서 검색을 수행하기 위해, Next.js 애플리케이션은 쿼리에 맞는 문서 청크를 검색하는 `@smart-doc/docs` 패키지의 함수를 호출하는 API 라우트를 포함합니다. 이 청크들을 사용하여 사용자의 검색과 관련된 문서 페이지 목록을 반환할 수 있습니다.
+
+챗봇 기능의 경우, 동일한 검색 과정을 따르지만 추가로 검색된 문서 청크를 ChatGPT에 보내는 프롬프트에 주입합니다.
+
+다음은 ChatGPT에 보내는 프롬프트 예시입니다:
+
+시스템 프롬프트:
+
+```txt
+당신은 Intlayer 문서에 관한 질문에 답변할 수 있는 유용한 도우미입니다.
+
+관련 청크:
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/ko/getting-started"
+---
+
+# 시작하는 방법
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/ko/another-doc"
+---
+
+# 다른 문서
+
+...
+```
+
+사용자 질의 :
+
+```txt
+시작하는 방법은?
+```
+
+우리는 API 경로에서 응답을 스트리밍하기 위해 SSE를 사용합니다.
+
+앞서 언급했듯이, 우리는 "생각하는" 모드 없이 gpt-4-turbo를 사용합니다. 응답은 관련성이 높고 지연 시간이 낮습니다.
+gpt-5도 실험해 보았지만, 지연 시간이 너무 길었고(때로는 응답에 최대 15초까지 걸림) 앞으로 다시 검토할 예정입니다.
+
+👉 [여기에서 데모를 시도해 보세요](https://intlayer.org/doc/why) 👉 [GitHub에서 코드 템플릿 확인하기](https://github.com/aymericzip/smart_doc_RAG)
+
+## 더 나아가기
+
+이 프로젝트는 최소한의 구현입니다. 하지만 여러 가지 방법으로 확장할 수 있습니다:
+
+- MCP 서버 → 문서 검색 기능을 MCP 서버로 확장하여 문서를 모든 AI 어시스턴트에 연결
+- 벡터 DB → 수백만 개의 문서 청크로 확장
+- LangChain / LlamaIndex → RAG 파이프라인을 위한 기성 프레임워크
+- 분석 대시보드 → 사용자 쿼리와 문제점을 시각화
+- 다중 소스 검색 → 문서뿐만 아니라 데이터베이스 항목, 블로그 게시물, 티켓 등도 검색
+- 향상된 프롬프트 → 재순위화, 필터링, 하이브리드 검색(키워드 + 의미 기반)
+
+## 우리가 직면한 한계
+
+- 청크 분할과 중첩은 경험적입니다. 적절한 균형(청크 크기, 중첩 비율, 검색된 청크 수)은 반복과 테스트가 필요합니다.
+- 문서가 변경될 때 임베딩이 자동으로 재생성되지 않습니다. 우리 시스템은 저장된 청크 수와 다를 때만 파일의 임베딩을 재설정합니다.
+- 이 프로토타입에서는 임베딩이 JSON에 저장됩니다. 이는 데모에는 적합하지만 Git을 오염시킵니다. 실제 운영 환경에서는 데이터베이스나 전용 벡터 스토어가 더 적합합니다.
+
+## 문서를 넘어 중요한 이유
+
+흥미로운 부분은 단순한 챗봇이 아닙니다. 바로 **피드백 루프**입니다.
+
+RAG를 사용하면 단순히 답변하는 것에 그치지 않습니다:
+
+- 사용자가 무엇에 혼란스러워하는지 알게 됩니다.
+- 사용자가 기대하는 기능을 발견합니다.
+- 실제 쿼리를 기반으로 제품 전략을 조정합니다.
+
+**예시:**
+
+새로운 기능을 출시하고 즉시 다음과 같은 상황을 상상해 보세요:
+
+- 질문의 50%가 동일한 불명확한 설정 단계에 관한 것
+- 사용자가 아직 지원하지 않는 통합 기능을 반복적으로 요청
+- 사람들이 새로운 사용 사례를 드러내는 용어를 검색
+
+이것이 바로 사용자로부터 직접 얻는 **제품 인텔리전스**입니다.
+
+## 결론
+
+RAG는 LLM을 실용적으로 만드는 가장 간단하면서도 강력한 방법 중 하나입니다. **검색(retrieval) + 생성(generation)**을 결합함으로써 정적인 문서를 **스마트 어시스턴트**로 전환할 수 있으며, 동시에 지속적인 제품 인사이트 흐름을 얻을 수 있습니다.
+
+저에게 이 프로젝트는 RAG가 단순한 기술적 트릭이 아님을 보여주었습니다. RAG는 문서를 다음과 같이 변환하는 방법입니다:
+
+- 상호작용하는 지원 시스템
+- 피드백 채널
+- 제품 전략 도구
+
+👉 [여기서 데모를 시도해보세요](https://intlayer.org/doc/why) 👉 [GitHub에서 코드 템플릿을 확인하세요](https://github.com/aymericzip/smart_doc_RAG)
+
+그리고 만약 여러분도 RAG를 실험하고 있다면, 어떻게 사용하고 있는지 듣고 싶습니다.