이제 Google 검색을 통한 그라운딩 기능을 사용할 수 있습니다. 자세히 알아보기

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Docs 에이전트를 사용하여 AI 콘텐츠 검색 빌드

정보 검색은 인공지능 (AI) 생성형 모델의 가장 일반적인 용도 중 하나입니다. AI를 사용하여 콘텐츠용 대화형 검색 인터페이스를 빌드하면 사용자가 구체적인 질문을 하고 직접적인 답변을 받을 수 있습니다.

이 튜토리얼에서는 콘텐츠용 AI 기반 대화형 검색 인터페이스를 빌드하는 방법을 보여줍니다. Docs Agent를 기반으로 하며, 이 오픈소스 프로젝트는 Google Gemini API를 사용하여 새로운 AI 모델을 학습하거나 Gemini 모델로 모델을 조정하지 않고 대화형 검색 인터페이스를 만듭니다. 즉, 이 검색 기능을 빠르게 빌드하여 크고 작은 콘텐츠 세트에 사용할 수 있습니다.

프로젝트에 대한 개요와 빌드한 사용자의 통계를 비롯한 확장 방법을 확인하려면 AI 콘텐츠 검색 | Google AI로 빌드를 참고하세요. 또는 아래 안내에 따라 프로젝트 확장을 시작할 수 있습니다.

개요

Docs Agent 프로젝트는 Google Gemini API 및 생성형 모델을 기반으로 특정 콘텐츠 세트에 대한 대화형 검색 인터페이스를 제공합니다. 사용자는 대화형 스타일로 자세한 질문을 하고 특정 콘텐츠 세트를 기반으로 자세한 답변을 받을 수 있습니다. 백그라운드에서 Docs 에이전트는 질문을 받아 콘텐츠의 벡터 데이터베이스를 검색하고 관련 텍스트 스니펫을 포함하여 생성형 모델을 위한 상세한 프롬프트를 만듭니다. 생성형 모델은 질문에 대한 응답을 생성하고 Docs Agent는 응답의 형식을 지정하여 사용자에게 표시합니다.

Docs 에이전트의 기능 다이어그램 그림 1. Docs Agent 프로젝트 앱의 기능 다이어그램

Docs 어시스턴트가 콘텐츠에 관한 질문에 답변할 수 있도록 하려면 콘텐츠의 벡터 데이터베이스를 만드는 것이 중요합니다. 콘텐츠를 논리적 텍스트 청크로 구분하고 각 청크에 대해 벡터를 생성합니다. 이러한 벡터는 각 청크의 정보를 수치로 표현한 것으로, Google의 생성형 모델에 있는 AI 텍스트 임베딩 함수로 생성됩니다.

사용자가 질문하면 Docs 어조 분석 도구는 동일한 텍스트 임베딩 함수를 사용하여 해당 질문의 숫자 표현을 만들고 이 값을 사용하여 벡터 데이터베이스를 검색하고 관련 콘텐츠를 찾습니다. 상위 결과를 가져와 생성형 모델의 프롬프트에 추가합니다. AI 모델은 질문과 추가 컨텍스트 정보를 사용하여 답변을 생성합니다.

프로젝트 설정

이 안내에서는 개발 및 테스트를 위해 Docs Agent 프로젝트를 설정하는 방법을 안내합니다. 일반적인 단계는 몇 가지 기본 소프트웨어를 설치하고, 몇 가지 환경 변수를 설정하고, 코드 저장소에서 프로젝트를 클론하고, 구성 설치를 실행하는 것입니다. 코드 프로젝트는 Python Poetry를 사용하여 패키지와 Python 런타임 환경을 관리합니다.

기본 요건 설치

Docs Agent 프로젝트는 Python 3 및 Python Poetry를 사용하여 패키지를 관리하고 애플리케이션을 실행합니다. 다음 설치 안내는 Linux 호스트 머신용입니다.

필수 소프트웨어를 설치하려면 다음 단계를 따르세요.

Python 3과 Python용 venv 가상 환경 패키지를 설치합니다.
```
sudo apt update
sudo apt install git pip python3-venv
```
Python Poetry를 설치하여 프로젝트의 종속 항목과 패키징을 관리합니다.
```
curl -sSL https://install.python-poetry.org | python3 -
```

프로젝트를 확장하는 경우 Python Poetry를 사용하여 Python 라이브러리를 추가할 수 있습니다.

환경 변수 설정하기

Google Gemini API 키 및 Python Poetry 설정을 비롯하여 Docs Agent 코드 프로젝트를 실행하는 데 필요한 몇 가지 환경 변수를 설정합니다. Linux를 사용하는 경우 터미널 세션의 기본 설정으로 만들기 위해 이러한 변수를 $HOME/.bashrc 파일에 추가하는 것이 좋습니다.

환경 변수를 설정하려면 다음 안내를 따르세요.

Google Gemini API 키를 가져와 키 문자열을 복사합니다.
API 키를 환경 변수로 설정합니다. Linux 호스트에서는 다음 명령어를 사용합니다.
```
export API_KEY=<YOUR_API_KEY_HERE>
```
PYTHON_KEYRING_BACKEND 매개변수를 설정하여 Python Poetry의 알려진 문제를 해결합니다. Linux 호스트에서는 다음 명령어를 사용합니다.
```
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring
```

프로젝트 복제 및 구성

프로젝트 코드를 다운로드하고 Poetry 설치 명령어를 사용하여 필요한 종속 항목을 다운로드하고 프로젝트를 구성합니다. 프로젝트 소스 코드를 가져오려면 git 소스 제어 소프트웨어가 필요합니다. 외부 프로젝트 코드를 다운로드하고 구성하려면 다음 단계를 따르세요.

다음 명령어를 사용하여 git 저장소를 클론합니다.
```
git clone https://github.com/google/generative-ai-docs
```
원하는 경우 Docs Agent 프로젝트의 파일만 포함되도록 스파스 체크아웃을 사용하도록 로컬 Git 저장소를 구성합니다.
```
cd generative-ai-docs/
git sparse-checkout init --cone
git sparse-checkout set examples/gemini/python/docs-agent/
```
docs-agent 프로젝트 루트 디렉터리로 이동합니다.
```
cd examples/gemini/python/docs-agent/
```
Poetry install 명령어를 실행하여 종속 항목을 다운로드하고 프로젝트를 구성합니다.
```
poetry install
```

콘텐츠 준비

Docs Agent 프로젝트는 텍스트 콘텐츠를 처리하도록 설계되었으며, 특히 마크다운을 소스 형식으로 사용하는 웹사이트를 처리하기 위한 도구가 포함되어 있습니다. 웹사이트 콘텐츠를 사용하는 경우 콘텐츠 처리 작업에서 해당 콘텐츠에 대한 링크를 매핑하고 만들 수 있도록 제공된 웹사이트의 디렉터리 구조를 보존 (또는 복제)해야 합니다.

콘텐츠의 형식과 세부정보에 따라 비공개 정보, 내부 메모 또는 검색되지 않도록 하려는 기타 정보를 삭제하기 위해 콘텐츠를 정리해야 할 수 있습니다. 콘텐츠 처리 단계에서 논리적 텍스트 분할 또는 청크를 만드는 데 도움이 되는 제목 및 제목과 같은 기본 형식을 유지해야 합니다.

처리할 콘텐츠를 준비하려면 다음 단계를 따르세요.

AI 에이전트가 검색할 콘텐츠의 디렉터리를 만듭니다.
```
mkdir docs-agent/content/
```
콘텐츠를 docs-agent/content/ 디렉터리에 복사합니다. 콘텐츠가 웹사이트인 경우 제공되는 웹사이트의 디렉터리 구조를 보존 (또는 복제)합니다.
비공개 정보 또는 검색에 포함하고 싶지 않은 기타 정보를 삭제하기 위해 필요에 따라 콘텐츠를 정리하거나 수정합니다.

테스트에 Flutter 문서 사용

Docs Agent를 테스트하는 데 콘텐츠 세트가 필요한 경우 테스트에 Flutter 개발자 문서를 사용할 수 있습니다.

Flutter 개발자 문서를 가져오려면 다음 단계를 따르세요.

AI 상담사가 검색할 콘텐츠의 콘텐츠 디렉터리로 이동합니다.
```
cd docs-agent/content/
```

Flutter 문서를 docs-agent/content/ 디렉터리에 클론합니다.

git clone --recurse-submodules https://github.com/flutter/website.git

콘텐츠 처리

검색 에이전트가 사용자 질문과 관련된 콘텐츠를 효과적으로 검색하려면 콘텐츠를 나타내는 벡터 데이터베이스를 빌드해야 합니다. 벡터는 텍스트 임베딩이라는 AI 생성형 모델 함수를 사용하여 생성됩니다. 텍스트 임베딩은 텍스트 콘텐츠를 숫자로 표현한 것입니다. 텍스트의 의미론적 의미를 숫자 집합으로 근사합니다. 정보를 숫자로 표현하면 시스템이 사용자의 질문을 받아 동일한 텍스트 임베딩 함수를 사용하여 의미를 대략적으로 추정한 다음 k-최근접 이웃(k-NN) 알고리즘을 사용하여 관련 정보를 수학적 계산으로 찾을 수 있습니다.

텍스트 콘텐츠 분할

텍스트 임베딩 벡터가 효과적으로 표현할 수 있는 텍스트의 양은 제한적입니다. 이 프로젝트는 벡터로 표현된 텍스트를 3,000자(영문 기준) 이하로 제한합니다. 즉, 콘텐츠를 글자 수 제한에 맞게 청크로 분할해야 합니다. 이 섹션에서는 Docs Agent 프로젝트와 함께 제공된 스크립트를 사용하여 Markdown 파일을 더 작은 텍스트 청크로 분할하는 방법을 설명합니다. 다른 콘텐츠 형식을 사용하는 방법에 관한 도움말은 다른 형식 처리를 참고하세요.

마크다운 형식 콘텐츠를 분할하려면 다음 단계를 따르세요.

docs-agent/config.yaml 파일을 수정하여 처리 스크립트의 입력 매개변수를 구성합니다. 이 예에서는 Flutter 문서의 하위 집합을 타겟팅합니다.
```
input:
- path: "content/website/src/ui"
  url_prefix: "https://docs.flutter.dev/ui"
```
변경사항을 이 구성 파일에 저장합니다.
docs-agent 프로젝트 디렉터리로 이동합니다.
```
cd docs-agent/
```
agent chunk 명령어를 실행하여 마크다운 소스 콘텐츠를 분할합니다.
```
agent chunk
```

이 스크립트는 입력 콘텐츠를 처리하고 docs-agent/data 디렉터리에 출력 텍스트 파일을 만들어 제목, 제목, 관련 단락을 기준으로 텍스트를 분할합니다. 콘텐츠 크기에 따라 처리하는 데 다소 시간이 걸릴 수 있습니다.

텍스트 임베딩 벡터 만들기

콘텐츠를 적절한 크기의 의미 있는 청크로 분할한 후 텍스트 임베딩 함수를 사용하여 벡터 데이터베이스를 콘텐츠로 채울 수 있습니다. Docs Agent 프로젝트는 Chroma 벡터 데이터베이스를 사용하여 텍스트 임베딩 벡터를 저장합니다. 이 안내에서는 Docs 에이전트 스크립트를 사용하여 분할된 콘텐츠로 벡터 데이터베이스를 채우는 방법을 설명합니다.

텍스트 임베딩을 생성하고 벡터 데이터베이스를 채우려면 다음 단계를 따르세요.

docs-agent 프로젝트 디렉터리로 이동합니다.
```
cd docs-agent/
```
agent populate 명령어를 사용하여 벡터 데이터베이스를 콘텐츠로 채웁니다.
```
agent populate
```

이 스크립트는 Google Gemini API를 사용하여 텍스트 임베딩 벡터를 생성한 후 출력을 벡터 데이터베이스에 저장합니다. 콘텐츠 크기에 따라 처리하는 데 다소 시간이 걸릴 수 있습니다.

기타 형식 처리

Docs 상담사 프로젝트는 마크다운 형식의 웹사이트 콘텐츠를 처리하도록 설계되었습니다. 프로젝트 작성자는 Google Docs, PDF, Gmail을 비롯한 다른 유형의 콘텐츠를 마크다운 형식으로 생성하는 몇 가지 변환 스크립트를 빌드했습니다. 이러한 변환기 사용에 관한 자세한 내용은 코드 저장소의 docs-agent/apps_script 디렉터리를 참고하세요.

다른 콘텐츠 형식 변환

프로젝트에 다른 콘텐츠 형식을 사용할 수 있지만 이러한 추가 메서드는 개발자 또는 다른 커뮤니티 회원이 빌드해야 합니다. 코드 저장소의 Issues 및 Pull Requests에서 비슷한 솔루션을 빌드하는 사용자를 확인합니다.

다른 콘텐츠 형식을 지원하기 위해 빌드해야 하는 핵심 코드는 files_to_plain_text.py 스크립트와 같은 스플리터 스크립트입니다. 이 스크립트와 유사한 출력을 생성하는 스크립트나 프로그램을 빌드하는 것을 목표로 합니다. 최종 텍스트 출력에는 서식과 불필요한 정보가 최소한으로 포함되어야 합니다. HTML 또는 JSON과 같은 콘텐츠 형식을 사용하는 경우, 정보가 아닌 형식 (태그, 스크립팅, CSS)을 최대한 많이 삭제하여 이러한 형식에서 생성하는 텍스트 임베딩의 값이 왜곡되지 않도록 해야 합니다.

콘텐츠 형식의 스플리터 스크립트를 빌드하면 populate_vector_database.py 스크립트를 실행하여 벡터 데이터베이스를 채울 수 있습니다. Docs Agent와 함께 사용할 파일 처리에 관한 자세한 내용은 Docs Agent 사전 처리 리드미를 참고하세요.

앱 테스트

벡터 데이터베이스 채우기를 완료하면 프로젝트를 테스트할 준비가 됩니다. 이 프로젝트는 프로젝트를 로컬에서 실행할 수 있는 패키징 함수를 제공합니다.

프로젝트 웹 인터페이스를 실행하고 테스트하려면 다음 단계를 따르세요.

docs-agent 프로젝트 디렉터리로 이동합니다.
```
cd docs-agent/
```
웹 애플리케이션 실행 스크립트를 실행합니다.
```
agent chatbot
```
웹브라우저를 사용하여 실행 스크립트의 출력에 표시된 URL 웹 주소로 이동하고 애플리케이션을 테스트합니다.
```
* Running on http://your-hostname-here:5000
```

구현 옵션

Gemini API는 Docs 에이전트 구현의 구성요소, 특히 시맨틱 검색 및 기여 분석 질문 응답 (AQA) Gemini 모델 변형을 대체할 수 있는 프로그래밍 도구를 제공합니다. Gemini API의 시맨틱 검색 기능을 사용하여 별도의 벡터 데이터베이스를 대체할 수 있습니다. 시맨틱 검색 기능을 사용하면 콘텐츠의 임베딩을 생성하고 콘텐츠를 저장할 수 있습니다. AQA Gemini 모델은 프롬프트에 제공된 소스 자료로 질문에 답변하도록 조정됩니다. AQA 모델과 함께 시맨틱 검색을 사용하여 Gemini API 내에서 콘텐츠에 관한 질문에 답변합니다.

Docs Agent에는 Semantic Retrieval API 기능, AQA Gemini 모델 또는 둘 다를 사용하는 구성 옵션이 포함되어 있습니다. 자세한 내용은 Docs Agent Readme를 참고하세요.

추가 리소스

Docs Agent 프로젝트에 관한 자세한 내용은 코드 저장소를 참고하세요. 애플리케이션을 빌드하는 데 도움이 필요하거나 개발자 공동작업자를 찾고 있다면 Google 개발자 커뮤니티 Discord 서버를 확인하세요.

프로덕션 애플리케이션

많은 사용자를 위해 Docs Agent를 배포할 계획이라면 Google Gemini API 사용 시 비율 제한 및 기타 사용 제한사항이 적용될 수 있습니다. Docs Agent와 같은 Gemini API로 프로덕션 애플리케이션을 빌드하려는 경우 앱의 확장성과 안정성을 높이려면 Google Cloud Vertex AI 서비스를 확인하세요.