GoogleDriveRetriever

Drive API v3 검색 엔드포인트를 통해 Google Drive에서 파일을 검색해요.

출처: 문서

본문

GoogleDriveRetriever는 Drive API v3 files.list 엔드포인트를 통해 사용자의 Google Drive(그리고 선택적으로 공유 드라이브)를 전체 텍스트 검색하고, 일치하는 각 파일을 Haystack Document에 매핑해요.

기본적으로 각 Document는 리소스 메타데이터(file_name, file_id, web_url, mime_type, file_extension, 작성자, 타임스탬프)를 담고, Drive 검색 API가 텍스트 스니펫을 반환하지 않으므로 파일 description 또는 name을 content로 사용해요. include_content=True로 설정하면 네이티브 Google Docs/Sheets/Slides를 텍스트로 추가 내보내고 그 값을 Document 콘텐츠로 사용해요. 바이너리 파일(PDF, DOCX 등)은 리트리버가 절대 다운로드하지 않아요.

일치하는 파일의 전체 콘텐츠를 다운로드하려면 반환된 web_url/file_id에 GoogleDriveFetcher를 결합하고 이어서 컨버터를 붙이세요.

Authentication

리트리버는 run 입력으로 사용자별 access_token을 받아요. 토큰은 검색을 허용하는 위임된 Google OAuth 범위(예: https://www.googleapis.com/auth/drive.readonly)를 가져야 해요. 메타데이터 전용 drive.metadata.readonly 범위는 파일 콘텐츠 검색이나 문서 내보내기를 할 수 없어요. 일반적으로 토큰을 업스트림 OAuthTokenResolver에서 연결하며, 일반 문자열을 내보내요. Secret도 허용되고 내부적으로 해결돼요.

Scoping and filtering the search

query_filter: 전체 텍스트 검색어와 AND되는 선택적 Drive 쿼리 절(예: "mimeType != 'application/vnd.google-apps.folder'" 또는 "'<folderId>' in parents").
include_shared_drives: True면 검색이 사용자의 My Drive뿐 아니라 공유 드라이브에도 걸쳐요.
order_by: 선택적 Drive orderBy 표현식(예: "modifiedTime desc").

Installation

pip install google-drive-haystack

대표적인 파이프라인 위치: 쿼리 파이프라인의 시작, access_token을 제공하는 OAuthTokenResolver 뒤
필수 init 변수: 없음
필수 run 변수: query(검색 쿼리 문자열) / access_token(위임된 Google OAuth bearer 토큰)
출력 변수: documents — 파일 메타데이터(그리고 선택적으로 내보낸 텍스트)를 담은 Document 리스트
API reference: Google Drive
패키지명: google-drive-haystack

Usage

On its own

아래 access_token은 사용자별 위임된 Google OAuth bearer 토큰이에요. 프로덕션에서는 붙여넣는 대신 OAuthTokenResolver에서 얻을 거예요.

from haystack_integrations.components.retrievers.google_drive import (
    GoogleDriveRetriever,
)

retriever = GoogleDriveRetriever(top_k=5)
result = retriever.run(
    query="quarterly roadmap",
    access_token="my-delegated-google-token",
)
for doc in result["documents"]:
    print(doc.meta["file_name"], "-", doc.meta["web_url"])

In a pipeline

다음 파이프라인은 OAuthTokenResolver에서 토큰을 얻어 리트리버에 공급하므로, 파이프라인 실행에는 쿼리만 필요해요:

from haystack import Pipeline
from haystack.utils import Secret
from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
from haystack_integrations.components.retrievers.google_drive import (
    GoogleDriveRetriever,
)

pipeline = Pipeline()
pipeline.add_component(
    "resolver",
    OAuthTokenResolver(
        token_source=OAuthRefreshTokenSource(
            token_url="https://oauth2.googleapis.com/token",
            client_id="aaa-bbb-ccc",
            refresh_token=Secret.from_env_var("GOOGLE_REFRESH_TOKEN"),
            scopes=["https://www.googleapis.com/auth/drive.readonly"],
        ),
    ),
)
pipeline.add_component("retriever", GoogleDriveRetriever(top_k=5))
pipeline.connect("resolver.access_token", "retriever.access_token")
result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
documents = result["retriever"]["documents"]

검색된 파일의 전체 콘텐츠를 다운로드·변환하려면 리트리버의 documents 출력을 GoogleDriveFetcher에 연결하세요. 그 페이지에서 retrieve-fetch-convert 종단 간 예시를 볼 수 있어요.

GoogleDriveRetriever