Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

데이터 스토어에서 문서 검색

관리형 수집 파이프라인은 데이터 스토어에서 에이전트 검색으로 문서를 가져와 텍스트 쿼리로 검색할 수 있는 데이터 객체 및 컬렉션으로 변환하고 파싱, 세분화, 임베딩, 색인 생성을 자동으로 처리합니다.

지원되는 문서 형식

다음 표에는 지원되는 문서 파일 형식과 파일 확장자가 나와 있습니다.

문서 유형	파일 확장자
PDF	`.pdf`
일반 텍스트	`.txt`
Microsoft Word	`.docx`
Microsoft Excel	`.xlsx`
Microsoft 매크로 사용 설정 Excel	`.xlsm` (스크립트 및 매크로는 무시됨)
Microsoft PowerPoint	`.pptx`

기본 요건

시작하기 전에 다음이 필요합니다.

Google Cloud 프로젝트 Google Cloud 프로젝트를 만드는 방법은 프로젝트 및 개발 환경 설정을 참조하세요.
검색하려는 파일이 포함된 Cloud Storage 버킷
버킷 프로젝트의 서비스 에이전트 service-PROJECT_NUMBER@gcp-sa-vectorsearch.iam.gserviceaccount.com에 부여된 roles/vectorsearch.serviceAgent 권한

예시

이 페이지의 예시는 다음 샘플 파일을 기반으로 합니다.

curl

PROJECT=acme-prod
LOCATION=us-east4
BASE=https://vectorsearch.googleapis.com/v1alpha
INGEST=${BASE}/projects/${PROJECT}/locations/${LOCATION}
AUTH="Authorization: Bearer $(gcloud auth print-access-token)"

Python

import time
import google.auth
from google.auth.transport.requests import AuthorizedSession

PROJECT = "acme-prod"          # Replace with your project ID
LOCATION = "us-east4"          # Replace with your region

credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(credentials)

BASE = "https://vectorsearch.googleapis.com/v1alpha"
INGEST = BASE + "/projects/" + PROJECT + "/locations/" + LOCATION

def wait(operation, poll_seconds=10):
    """Poll a long-running operation until it finishes, then return it."""
    name = operation["name"]
    while True:
        op = session.get(BASE + "/" + name).json()
        if op.get("done"):
            if "error" in op:
                raise RuntimeError(op["error"])
            return op
        meta = op.get("metadata", {})
        print("in progress:", meta)
        time.sleep(poll_seconds)

관리형 수집 파이프라인

관리형 수집 파이프라인은 데이터 스토어에서 에이전트 검색으로 문서를 가져오고 데이터 객체 및 컬렉션을 설정하는 대부분의 작업을 수행합니다.

다음과 같이 하면 됩니다.

파일을 스테이징합니다.
데이터 스토어를 만듭니다.
파일을 가져옵니다.
텍스트 쿼리로 파일을 검색합니다.

1. 파일 스테이징

버킷을 만들고 검색할 파일을 추가합니다. 매니페스트를 만들 필요가 없습니다.

문서 관리형 수집:

200MB를 초과하는 문서는 건너뜁니다.
Microsoft 매크로 사용 설정 Excel (.xlsm) 문서의 매크로 및 스크립트를 무시합니다.
한 번에 100,000개의 문서만 가져옵니다.

파일의 메타데이터를 정의하는 JSONL을 스테이징할 수도 있습니다. 자세한 내용은 파일에 메타데이터 추가를 참고하세요.

2. 데이터 스토어 만들기

검색할 파일을 스테이징한 후 데이터 스토어를 만들어야 합니다. 데이터 스토어는 관리형 수집 파이프라인의 소스와 파일 수집 방법을 지정하는 구성을 제공합니다.

관리형 수집은 us-east4 또는 europe-west4 리전에 있는 데이터 스토어에만 사용할 수 있습니다.

데이터 스토어를 만들려면 dataStores API에 POST 요청을 수행하고 다음 매개변수를 제공합니다.

data_store_id: 생성 중인 데이터 스토어의 ID입니다. 소문자로 시작하고 소문자 또는 숫자로 끝나야 하며 소문자, 숫자, 하이픈만 포함하고 길이는 1~63자(영문 기준)여야 합니다.

JSON 페이로드에는 관리형 수집에서 데이터 스토어를 만들고 스테이징한 문서를 처리하는 데 사용하는 JSON 구성 설정이 포함되어 있습니다.

JSON 페이로드에는 최상위 속성 document_type가 포함되어야 합니다. 데이터 스토어에서 가져올 파일 형식을 지정합니다. 유효한 값은 다음과 같습니다.

UNSTRUCTURED: 데이터 스토어에 문서가 포함되어 있습니다. 지원되는 형식 목록은 지원되는 문서 형식을 참조하세요.
VIDEO: 데이터 스토어에 동영상이 포함되어 있습니다.

다음 속성은 선택사항입니다.

display_name: (STRING) 데이터 스토어의 표시 이름입니다. 최대 크기는 1,024바이트입니다. 기본값은 빈 문자열입니다.
description: (STRING) 데이터 스토어의 설명입니다. 최대 크기는 1,024바이트입니다. 기본값은 빈 문자열입니다.
labels: (STRING 배열) 키-값 쌍의 배열입니다. 자세한 내용은 라벨을 사용한 리소스 구성을 참조하세요. 기본값은 빈 배열입니다.
processing_config(OBJECT): 관리형 수집이 데이터 스토어의 데이터를 처리하는 방법에 대한 구성입니다. PATCH 요청으로 업데이트할 수 있습니다. 생략된 경우의 기본 설정은 문서 데이터 스토어의 선택적 설정을 참조하세요.
document_metadata_schema(OBJECT): 데이터 스토어의 문서와 연결된 메타데이터의 메타데이터 스키마입니다. 자세한 내용은 메타데이터 스키마 추가를 참조하세요. 기본값은 빈 객체입니다 (메타데이터 스키마 없음).

문서 파일 설정(선택사항)

문서 데이터 스토어에는 다음과 같은 선택적 설정을 사용할 수 있습니다.

processing_config.unstructured_processing_config.segmentation_config: (OBJECT) 문서를 세분화하는 방법에 대한 수집 구성입니다 (검색은 문서가 아닌 세그먼트별로 수행됨). 자세한 내용은 문서 세분화를 참조하세요. 빈 객체는 INVALID_ARGUMENT 상태로 요청이 거부됩니다. 제공되는 경우 다음 중 하나를 포함해야 합니다.
- page_segmentation_config: (OBJECT) 이 객체에는 속성이 없습니다.
- chunk_segmentation_config: (OBJECT) 다음 속성이 있습니다.
- chunk_size: (INTEGER) 세그먼트의 최대 토큰 수입니다. 최솟값은 300이고 최댓값은 500입니다. 기본값은 500입니다.
- include_ancestor_headings: (BOOL) 컨텍스트를 위해 각 청크에 섹션 제목 체인을 추가합니다. 기본값은 false입니다.
processing_config.unstructured_processing_config.parsing_config: (OBJECT) 문서를 파싱하는 방법에 대한 수집 구성입니다. 자세한 내용은 문서 파싱을 참조하세요. 빈 객체는 INVALID_ARGUMENT 상태로 요청이 거부됩니다. 제공되는 경우 다음 중 하나를 포함해야 합니다.
- layout_parsing_config: (OBJECT) 레이아웃 파싱이 사용됩니다. 이 객체에는 속성이 없습니다.
- digital_parsing_config: (OBJECT) 디지털 파싱이 사용됩니다. 이 객체에는 속성이 없습니다.
processing_config.unstructured_processing_config.embedding_config.mode: (STRING) 사용할 임베딩 모드입니다. 다음 중 하나일 수 있습니다.
- TEXT: 추출된 텍스트만 임베딩됩니다. 이미지는 무시됩니다. 기본값은 TEXT입니다.

데이터 스토어에 메타데이터를 추가할 수도 있습니다. 자세한 내용은 파일에 메타데이터 추가를 참조하세요.

예시

다음 예시에서는 문서 데이터 스토어를 만드는 방법을 보여줍니다.

curl

  curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores?data_store_id=acme-financials" \
  -d '{
    "display_name": "Acme financial reports",
    "document_type": "UNSTRUCTURED",
    "processing_config": {
      "unstructured_processing_config": {
        "segmentation_config": {
          "chunk_segmentation_config": {
            "chunk_size": 300,
            "include_ancestor_headings": true
          }
        },
        "parsing_config": {
          "layout_parsing_config": {}
        }
      }
    }
  }'

Python

  op = session.post(
    INGEST + "/dataStores",
    params={"data_store_id": "acme-financials"},
    json={
        "display_name": "Acme financial reports",
        "document_type": "UNSTRUCTURED",
        "processing_config": {
            "unstructured_processing_config": {
                "segmentation_config": {
                    "chunk_segmentation_config": {
                        "chunk_size": 300,
                        "include_ancestor_headings": True,
                    }
                },
                "parsing_config": {"layout_parsing_config": {}},
            }
        },
    },
).json()

wait(op)

샘플 응답

  "name": "projects/acme-prod/locations/us-east4/dataStores/acme-financials",
  "documentType": "UNSTRUCTURED",
  "state": "ACTIVE",
  "collectionName": "projects/acme-prod/locations/us-east4/collections/google-acme-financials"
}

파일에 메타데이터 추가하기

관리형 처리를 통해 가져올 파일의 메타데이터 속성을 정의할 수 있습니다. 이러한 속성은 파이프라인에서 만든 해당 데이터 객체에서 검색할 수 있으며 검색 결과 필터링에 유용합니다.

메타데이터를 정의하려면 다음 안내를 따르세요.

JSONL 파일을 만듭니다. 확장자는 json 또는 jsonl이어야 합니다.
가져오려는 모든 파일의 새 줄에 JSON 객체를 추가하고 다음 속성을 포함합니다.
- name: 데이터 스토어에 있는 파일의 이름입니다. 이름의 마지막 세그먼트는 파일에 대해 생성된 데이터 객체의 ID로 사용됩니다.
- content.gcsUri: Cloud Storage에 있는 문서의 URI입니다.
- metadata.value: 문서의 메타데이터입니다. 메타데이터 속성은 데이터 스토어를 만들 때 지정하는 스키마에 정의됩니다. 자세한 내용은 메타데이터 스키마 추가를 참조하세요.

다음 예시는 category, year, tags, issuer 메타데이터 속성이 있는 메타데이터 JSONL을 보여줍니다.

{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/q3-earnings","content":{"gcsUri":"gs://acme-docs/reports/2025-q3-earnings.pdf"},"metadata":{"value":{"category":"earnings","year":2025,"tags":["revenue"],"issuer":{"country":"US"}}}}
{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/covenants","content":{"gcsUri":"gs://acme-docs/reports/covenant-summary.docx"},"metadata":{"value":{"category":"covenant","year":2024,"tags":["credit","debt"]}}}

속성은 데이터 스토어를 만들 때 제공하는 스키마와 일치해야 합니다.

파일을 가져올 때 만든 JSONL 파일을 입력 URI로 사용합니다.

메타데이터 스키마 추가

데이터 스토어의 JSON 구성에서 최상위 document_metadata_schema 속성에 메타데이터 스키마를 제공할 수 있습니다. 이는 문서와 연결할 수 있는 메타데이터의 계약을 정의하며, 문서별로 검색하거나 검색 결과를 필터링하는 데 사용할 수 있습니다.

메타데이터 속성은 데이터 스토어를 만들 때 제공하는 스키마와 일치해야 합니다. 스키마는 JSON 스키마 초안 7을 따릅니다. 지원되는 데이터 유형은 다음과 같습니다.

string
number
integer
boolean
object (속성 포함)
array

속성 이름에는 문자, 숫자, 밑줄 (_), 하이픈(-)만 사용할 수 있으며 google (대소문자 구분 없음)로 시작하면 안 됩니다. 프리픽스는 서비스가 작성하는 필드에 예약됩니다.

나중에 PATCH 요청을 사용하여 광고 속성을 추가할 수 있습니다. 스키마의 속성은 삭제하거나 데이터 유형을 변경할 수 없습니다. 자세한 내용은 처리 구성 업데이트를 참조하세요.

다음 예시에서는 category, year, tags, issuer 메타데이터 속성을 사용하여 메타데이터 스키마를 정의합니다.

"document_metadata_schema": {
  "schema": {
    "type": "object",
    "properties": {
      "category": {"type": "string"},
      "year":     {"type": "integer"},
      "tags":     {"type": "array", "items": {"type": "string"}},
      "issuer":   {"type": "object", "properties": {"country": {"type": "string"}}}
    }
  }
}

처리 구성 업데이트

데이터 스토어가 생성된 후 PATCH 요청을 사용하여 처리 구성 (processing_config)을 업데이트할 수 있습니다.

다음 속성을 업데이트할 수 있습니다.

display_name
description
labels
document_metadata_schema (추가 속성만 추가할 수 있음)

업데이트 중인 속성은 update_mask 쿼리 파라미터에 포함되어야 합니다.

다음 예시에서는 처리 구성의 display_name 및 document_metadata_schema 속성을 업데이트하는 방법을 보여줍니다.

curl

curl -X PATCH -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme-financials?update_mask=display_name,document_metadata_schema" \
-d '{"display_name": "Acme reports",
"document_metadata_schema": {"schema": {"type": "object", "properties": {
"category": {"type": "string"}, "year": {"type": "integer"},
"region": {"type": "string"}}}}}'

문서 분할

데이터 스토어를 만들 때 관리형 수집 파이프라인이 문서를 세분화하는 방법을 지정할 수 있습니다.

페이지 세분화 (processing_config.segmentation_config.page_segmentation_config): 관리형 수집은 페이지별로 문서를 세분화하려고 시도합니다.
청크 세분화 (processing_config.segmentation_config.chunk_segmentation_config): 관리형 수집은 문서를 별도의 청크로 세분화합니다.

지정하지 않으면 기본값은 청크 세분화입니다. 둘 다 지정하면 요청이 실패합니다.

페이지 세분화

페이지 세분화 (processing_config.segmentation_config.page_segmentation_config)를 지정하면 관리형 수집 파이프라인이 페이지 또는 페이지 범위별로 문서를 세분화합니다. 텍스트 파일과 같이 문서에 페이지 정보가 포함되지 않은 경우 최대 2.5MB 크기의 페이지로 세분화됩니다.

페이지 세분화는 각 검색 결과와 함께 PDF 또는 Word 문서를 반환하는 애플리케이션과 같은 문서 검색에 최적화되어 있습니다. 자세한 내용은 RAG용 문서 청크 처리를 참조하세요.

청크 세분화

청크 세분화 (processing_config.segmentation_config.chunk_segmentation_config)를 지정하면 관리형 수집 파이프라인이 문서를 최대 processing_config.segmentation_config.chunk_segmentation_config.chunk_size 토큰의 청크로 세분화합니다. 기본적으로 청크 크기는 500토큰 (최대 청크 크기)입니다. 최소 청크 크기는 300입니다.

큰 청크:

더 많은 컨텍스트를 전달합니다.
세그먼트 수를 줄입니다.
쿼리와 일치하지 않는 여러 주제를 다룰 수 있으므로 관련 정보가 묻힐 수 있습니다.

작은 청크:

더 좁은 텍스트 조각을 전달합니다.
쿼리와 일치하는 정보만 포함할 가능성이 높습니다.
컨텍스트를 적게 전달하므로 관련 정보를 여러 세그먼트로 분할할 수 있습니다.

대부분의 긴 형식 콘텐츠에는 청크 크기 500 토큰이 적합합니다. 청크 크기가 작을수록 짧은 사실 기반 콘텐츠나 간결하고 정확한 텍스트 구절을 검색하는 데 더 적합합니다.

입력 URI

gcs_source.input_uris JSON 속성은 관리형 수집 요청의 입력을 지정하는 문자열 배열입니다. 예를 들어 데이터 스토어에서 가져올 파일이나 에이전트 검색에서 삭제할 항목을 지정합니다.

gcs_source.source_format가 지정되지 않았거나 SOURCE_FORMAT_UNSPECIFIED (기본값)로 설정된 경우 입력 URI는 다음과 같을 수 있습니다.

하나 이상의 특정 URI입니다.
하나 이상의 와일드 카드 패턴
하나 이상의 텍스트 파일
- 문서 ID는 한 줄에 하나씩 정의됩니다. 빈 줄은 무시되고 각 줄에서 공백이 잘립니다.

gcs_source.source_format가 SOURCE_FORMAT_DOCUMENT_JSON로 설정된 경우 입력 URI는 JSONL 형식으로 정의됩니다. 자세한 내용은 문서에 메타데이터 추가를 참조하세요.

와일드 카드

패턴	일치
`gs://acme/files/hello_world.xyz`	지정된 파일입니다.
`gs://acme/files/*`	`gs://acme/files/`에서 지정된 `document_type`과 직접 일치하는 모든 파일
`gs://acme/files/*.xyz`	확장자가 `.xyz`인 모든 파일

와일드 카드는 재귀적이지 않습니다. 예를 들어 gs://acme/files/*을 지정하면 gs://acme/files/2025/ 아래의 파일을 가져오지 않습니다. 와일드 카드 **는 *와 동일하게 해석됩니다. 계층 구조를 평면화하거나 수준당 하나의 패턴을 전달하여 이 문제를 해결할 수 있습니다.

패턴이 일치하지 않으면 요청이 실패합니다. 예를 들어 URI 4개를 전달하고 그중 하나에 오타가 있는 경우 나머지 URI 3개로 가져오기가 계속되지 않습니다. 가져오기 요청을 하기 전에 각 URI가 올바른지 확인하세요.

3. 파일 가져오기

파이프라인의 다음 단계는 수집하려는 데이터 스토어에 있는 파일의 URI를 사용하여 importDocuments를 호출하는 것입니다.

다음 예시는 문서를 가져오는 방법을 보여줍니다.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/reports/*"]
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {"input_uris": ["gs://acme-docs/reports/*"]},
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors/"
        },
    },
).json()

result = wait(op)
print(result["metadata"]["successCount"], "imported")
# failureCount is not set on import metadata; check error files instead.

원하는 경우 메타데이터와 함께 가져올 수 있습니다. 자세한 내용은 문서에 메타데이터 추가를 참조하세요.

다음 예시는 메타데이터 JSONL 파일을 가져오는 방법을 보여줍니다.

curl

gcloud storage cp docs.jsonl gs://acme-docs/manifests/docs.jsonl
curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
      "source_format": "SOURCE_FORMAT_DOCUMENT_JSON"
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {
            "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
            "source_format": "SOURCE_FORMAT_DOCUMENT_JSON",
        },
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
        },
    },
).json()

result = wait(op)

컬렉션 관리형 처리는

데이터 스토어를 만들면 관리형 수집은 공개 에이전트 검색 API를 사용하여 에이전트 검색에 컬렉션을 만들고 다른 에이전트 검색 컬렉션과 마찬가지로 사용할 수 있습니다. 가져오기 작업이 완료될 때까지 컬렉션은 비어 있습니다.

컬렉션을 쿼리하는 방법에 대한 자세한 내용은 문서 검색을 참조하세요.

다음 예시는 데이터 스토어에서 컬렉션 이름을 가져오는 방법을 보여줍니다.

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials"

Python

data_store = session.get(INGEST + "/dataStores/acme-financials").json()
collection_name = data_store["collectionName"]
print(collection_name)

가져오기 진행 상황 추적

가져오기 작업의 진행 상황을 추적하려면 버킷 상태를 확인하는 대신 작업을 폴링합니다. 응답의 successCount 필드는 성공적으로 가져온 파일 수를 제공합니다.

오류를 수정하고 다른 가져오기 요청을 만들어 다시 시도할 수 있습니다. 자세한 내용은 가져오기 작업 다시 실행을 참조하세요.

다음 예시에서는 작업을 폴링하는 방법을 보여줍니다.

curl

curl -H "${AUTH}" "${BASE}/{OPERATION_NAME}"

Python

# To check once, without blocking, using the op returned by the import call:
status = session.get(BASE + "/" + op["name"]).json()
print(status.get("done"), status.get("metadata", {}))

다음 예시에서는 가져오기 작업이 완료된 후 가져온 파일 목록을 가져오는 방법을 보여줍니다.

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials/documents"

Python

docs = session.get(INGEST + "/dataStores/acme-financials/documents").json()
print(len(docs.get("documents", [])))

가져오기 작업 다시 실행

동일한 버킷에서 추가 가져오기 작업을 실행하면 수정되거나 추가된 파일만 처리됩니다. 이미 가져왔고 변경되지 않은 파일은 건너뜁니다.

문서 검색

관리형 수집에서 생성하는 컬렉션은 일반 에이전트 검색 컬렉션과 동일합니다. 쿼리하고 결과를 필터링하고, 순위를 다시 매기고, 색인을 생성하는 등의 작업을 할 수 있습니다.

예시

다음 예시에서는 데이터 스토어에서 가져온 파일의 콘텐츠를 검색하는 방법을 보여줍니다.

curl

COLLECTION=projects/${PROJECT}/locations/${LOCATION}/collections/google-acme-financials

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "https://vectorsearch.googleapis.com/v1/${COLLECTION}/dataObjects:search" \
  -d '{
    "semantic_search": {
      "search_text": "what is the total revenue?",
      "search_field": "multimodal_embedding",
      "task_type": "RETRIEVAL_QUERY",
      "top_k": 10,
      "output_fields": {
        "data_fields": ["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"]
      }
    }
  }'

Python

from google.cloud import vectorsearch_v1

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request argument(s)
semantic_search = vectorsearch_v1.SemanticSearch(
    search_text="what is the total revenue?",
    search_field="multimodal_embedding",
    task_type=vectorsearch_v1.EmbeddingTaskType.RETRIEVAL_QUERY,
    top_k=10,
    output_fields=vectorsearch_v1.OutputFields(
        data_fields=["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"],
    ),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    semantic_search=semantic_search,
)

# Make the request
response = search_client.search_data_objects(request=request)

# Handle the response
for hit in response.results:
    data = dict(hit.data_object.data)
    print(hit.distance, data["google_customer_uri"][0])
    print(data["google_unstructured_details"]["content_snippet"][:200])

검색 결과

각 검색 결과에는 다음 속성이 포함됩니다.

속성	유형	설명
`google_document_id`	문자열	세그먼트가 속한 문서입니다.
`google_customer_uri`	문자열	인용할 원본 `gs://` URI입니다.
`google_modality`	문자열	`UNSTRUCTURED` 또는 `VIDEO`.
`google_unstructured_details.content_snippet`	문자열	세그먼트 텍스트입니다.
`google_unstructured_details.start_page`/`end_page`	정수	청크의 페이지 스팬입니다. 디지털 파싱이 필요한 페이지 세분화로만 채워집니다. 청크 세분화의 경우 비어 있습니다.
`google_video_details.start_offset_nanos`/`end_offset_nanos`	정수	동영상 세그먼트의 기간입니다.
`multimodal_embedding`	벡터, 밀집, 768차원	`gemini-embedding-2`의 청크 임베딩입니다.
`metadata`	객체	문서에서 각 세그먼트로 복사되며, 선언된 대로 접두사가 없고 중첩됩니다 (예: `category` 또는 `issuer.country`).

start_page, end_page, start_offset_nanos, end_offset_nanos 속성은 지정된 문서 유형과 관계없이 항상 반환됩니다.

텍스트 문서의 경우 데이터 스토어가 생성될 때 페이지 세분화가 지정된 경우에만 start_page 및 end_page가 채워집니다.

metadata의 속성은 가져오기 중에 제공된 JSON 스키마에 해당합니다.

파일 삭제

데이터 스토어에서 파일을 삭제하려면 삭제할 파일의 ID가 각 줄에 포함된 하나 이상의 텍스트 파일을 Cloud Storage에 업로드합니다. 텍스트 파일의 URI를 purgeDocuments에 전달합니다.

응답에는 삭제된 파일이 표시되지 않습니다. 파일이 영구 삭제되었는지 확인하려면 GetDocument을 호출합니다. 응답은 404를 반환합니다.

force를 false로 설정하여 먼저 삭제 작업을 테스트합니다. 이렇게 하면 삭제될 파일이 지정한 error_gcs_prefix에 로깅됩니다.

파일이 영구 삭제되면 영구 삭제된 파일이 포함된 데이터 스토어를 삭제할 수 있습니다.

다음 예시는 파일을 영구 삭제하는 방법을 보여줍니다.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme:purgeDocuments" \
-d '{
  "gcs_source": {
    "input_uris": ["gs://acme/purge/purge-ids.txt"]
  },
  "purge_output_config": {
    "error_gcs_prefix": "gs://acme/purge-force-errors/"
  },
  "force": true
}'

Python

op = session.post(
  INGEST + "/dataStores/acme:purgeDocuments",
  json={
      "gcs_source": {
            "input_uris": ["gs://acme/purge/purge-ids.txt"],
        },
        "purge_output_config": {
            "error_gcs_prefix": "gs://acme/purge-force-errors/",
        },
        "force": True,
    },
).json()

result = wait(op)

데이터 스토어 삭제

데이터 스토어 URI와 함께 DELETE 요청을 전송하여 데이터 스토어를 삭제합니다. force가 true로 설정되어 있고 데이터 스토어에 여전히 파일이 포함되어 있으면 요청이 FAILED_PRECONDITION 상태 및 DataStore deletion is not allowed because it still contains documents. Set force=true to delete the DataStore and all its Documents. 메시지와 함께 실패합니다.

데이터 스토어를 가져온 후 생성된 컬렉션 및 데이터 객체를 삭제하려면 backing_collection_deleted를 true로 설정합니다. 이렇게 하지 않으면 컬렉션 및 데이터 객체가 남아 할당량을 계속 사용하며 동일한 ID로 새 데이터 스토어를 만들라는 요청은 FAILED_PRECONDITION (BACKING_COLLECTION_ALREADY_EXISTS) 메시지와 함께 실패합니다.

삭제 요청이 실행 중일 때 get 요청은 완료 후 DELETING 상태와 404 오류를 반환합니다.

다음 예시에서는 데이터 스토어를 삭제하는 방법을 보여줍니다.

curl

curl -X DELETE -H "${AUTH}" \
  "${INGEST}/dataStores/acme-financials?force=true&backing_collection_deleted=true"

Python

op = session.delete(
  INGEST + "/dataStores/acme-financials",
  params={"force": "true", "backing_collection_deleted": "true"},
).json()

result = wait(op)

데이터 스토어에서 문서 검색 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

지원되는 문서 형식

기본 요건

예시

curl

Python

관리형 수집 파이프라인

1. 파일 스테이징

2. 데이터 스토어 만들기

문서 파일 설정(선택사항)

예시

curl

Python

파일에 메타데이터 추가하기

메타데이터 스키마 추가

처리 구성 업데이트

curl

문서 분할

페이지 세분화

청크 세분화

입력 URI

와일드 카드

3. 파일 가져오기

curl

Python

curl

Python

컬렉션 관리형 처리는

curl

Python

가져오기 진행 상황 추적

curl

Python

curl

Python

가져오기 작업 다시 실행

문서 검색

예시

curl

Python

검색 결과

파일 삭제

curl

Python

데이터 스토어 삭제

curl

Python

데이터 스토어에서 문서 검색