새로운 Gemini API 설명서와 커뮤니티 포럼을 확인하세요.

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

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

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

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

AI 콘텐츠 검색 | Google AI로 빌드에서 프로젝트 및 프로젝트 확장 방법에 관한 동영상 개요와 프로젝트 빌드 담당자들의 유용한 정보를 확인해 보세요. 그렇지 않은 경우 아래 안내에 따라 프로젝트 확장을 시작할 수 있습니다.

개요

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

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

Docs 에이전트가 콘텐츠에 대한 질문에 답할 수 있게 하는 핵심은 해당 콘텐츠의 벡터 데이터베이스를 만드는 것입니다. 콘텐츠를 논리적 텍스트 청크로 분리하고 각 청크에 대한 벡터를 생성합니다. 이러한 벡터는 각 청크에 있는 정보를 숫자로 표현한 것이며 Google 생성 모델의 AI 텍스트 임베딩 함수로 생성됩니다.

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

프로젝트 설정

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

기본 요건 설치

문서 에이전트 프로젝트는 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 시를 사용하여 더 많은 Python 라이브러리를 추가할 수 있습니다.

환경 변수 설정하기

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

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

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

프로젝트 클론 및 구성

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

다음 명령어를 사용하여 git 저장소를 클론합니다.
```
git clone https://github.com/google/generative-ai-docs
```
원하는 경우 Docs 에이전트 프로젝트의 파일만 보유하도록 스파스 결제를 사용하도록 로컬 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 설치 명령어를 실행하여 종속 항목을 다운로드하고 프로젝트를 구성합니다.
```
poetry install
```

콘텐츠 준비

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

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

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

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

Flutter 문서를 사용하여 테스트

Docs 에이전트를 테스트하기 위한 콘텐츠가 필요한 경우 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 에이전트 프로젝트와 함께 제공되는 스크립트를 사용하여 마크다운 파일을 작은 텍스트 청크로 분할하는 방법을 설명합니다. 다른 콘텐츠 형식 작업에 관한 도움말은 다른 형식 처리를 참고하세요.

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

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 디렉터리에 출력 텍스트 파일을 만들어 제목, 제목, 관련 단락을 기준으로 텍스트를 분할합니다. 콘텐츠의 크기에 따라 처리하는 데 다소 시간이 걸릴 수 있습니다.

텍스트 임베딩 벡터 만들기

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

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

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

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

다른 형식 처리

Docs 에이전트 프로젝트는 마크다운 형식의 웹사이트 콘텐츠와 함께 작동하도록 설계되었습니다. 프로젝트 작성자는 Google Docs, PDF (Portable Document Format), Gmail 등 다른 유형의 콘텐츠를 마크다운 형식으로 생성하기 위한 변환기 스크립트를 몇 개 빌드했습니다. 이러한 변환기를 사용하는 방법에 관한 자세한 내용은 코드 저장소의 docs-agent/apps_script 디렉터리를 참조하세요.

다른 콘텐츠 형식 변환

프로젝트에서 다른 콘텐츠 형식을 사용할 수 있지만 이러한 추가 메서드는 개발자나 커뮤니티의 다른 구성원이 만들어야 합니다. 유사한 솔루션을 빌드하는 사람들은 코드 저장소 Issues와 Pull Request를 확인하세요.

다른 콘텐츠 형식을 지원하기 위해 빌드해야 하는 키 코드는 files_to_plain_text.py 스크립트와 같은 분할기 스크립트입니다. 이 스크립트와 유사한 출력을 생성하는 스크립트 또는 프로그램을 빌드하는 것을 목표로 합니다. 최종 텍스트 출력에는 최소한의 형식과 관련 없는 정보가 있어야 합니다. HTML 또는 JSON과 같은 콘텐츠 형식을 사용하는 경우 정보 이외의 형식 (태그, 스크립팅, CSS)을 최대한 많이 제거하여 이러한 형식에서 생성하는 텍스트 임베딩의 값이 왜곡되지 않도록 합니다.

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

앱 테스트

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

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

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

구현 옵션

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

Docs 에이전트에는 Semantic Retrieval API 기능, 해당 AQA Gemini 모델 또는 둘 다를 사용할 수 있는 구성 옵션이 포함되어 있습니다. 자세한 내용은 Docs 에이전트 리드미를 참조하세요.

추가 리소스

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

프로덕션 애플리케이션

대규모 사용자를 대상으로 Docs 에이전트를 배포하려는 경우 Google Gemini API 사용에 비율 제한 및 기타 사용 제한이 적용될 수 있습니다. Docs 에이전트와 같은 Gemini API로 프로덕션 애플리케이션을 빌드하려는 경우 Google Cloud Vertex AI 서비스를 확인하여 앱의 확장성과 안정성을 높이세요.