Cloud Storage 수집 파이프라인

이 문서에서는 Cloud Storage 수집 파이프라인의 기능과 파이프라인을 실행하는 방법을 설명합니다.

Cloud Storage 수집 파이프라인은 어떤 작업을 하나요?

사용자는 Cloud Storage에서 Document AI Warehouse로 문서를 전송할 수 있습니다. 여기에서 사용자는 검색, 문서 관리 워크플로 또는 단순히 Document AI 출력을 테스트하는 등의 작업을 위해 처리하도록 선택할 수 있습니다.

이 파이프라인을 사용해야 하는 이유

처리 여부와 관계없이 많은 문서를 수집해야 하는 경우 이 파이프라인은 안정적인 워크플로를 제공합니다. 또한 사용자가 개념 증명 또는 프로덕션 워크로드를 위해 Document AI Warehouse 고객의 온보딩 시간을 단축할 수 있습니다.

파이프라인 기능

일반적으로 Cloud Storage 수집 파이프라인은 다음 작업을 지원합니다.

원시 문서를 Document AI Warehouse에 수집합니다.

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
  }
}

Document AI에서 처리한 문서를 Document AI Warehouse로 수집합니다.
```
{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}
```
processor_type는 입력 파일이 Document AI로 처리되었음을 나타내는 데 필요합니다. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR)는 여기의 API 입력 필드에서 확인할 수 있습니다.

Document AI 처리 문서와 해당 원시 문서를 동일한 요청으로 인그레스합니다.

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}

input_path 위치에는 Document AI 처리 문서가 포함되어야 합니다. 파이프라인은 해당 URI 경로 아래에서 Doc AI 처리 문서별로 상응하는 원시 문서를 찾습니다.

한 유형의 원시 문서를 수집하고 파이프라인에서 Document AI 처리를 트리거합니다.

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    extract_processor_infos: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
      schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
    },
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

extract_processor_infos 필드에는 추출 프로세서가 하나만 포함되어야 합니다. input_path 필드 아래의 모든 문서는 하나의 문서 유형으로 간주되며 동일한 추출 프로세서에 의해 처리됩니다.

여러 유형의 원시 문서를 수집하고 파이프라인에서 Document AI 처리를 트리거합니다.

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    split_classify_processor_info: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
    },
    extract_processor_infos: [
      {
        processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
        document_type: "DOCUMENT_TYPE",
        schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
      }
    ],
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

split_classify_processor_info 필드는 유형별로 문서를 분류합니다. extract_processor_infos 필드 (배열로 전달됨)에는 분류 결과의 각 문서 유형에 해당하는 다양한 추출 프로세서가 포함되어야 합니다.

수집 구성

Cloud Storage 수집 파이프라인은 다음 옵션에 설명된 대로 문서 수집 중에 선택적 맞춤설정을 지원합니다.

파이프라인이 동일한 Cloud Storage 폴더에서 두 번 이상 트리거될 때 skip_ingested_documents 플래그를 사용하여 수집된 문서를 건너뜁니다. Cloud Storage의 문서에 파이프라인의 상태 추적 기능인 status=ingested 메타데이터가 포함되어 있으면 이 플래그가 사용 설정된 경우 문서가 다시 인제스트되지 않습니다.
문서 생성 중에 document_acl_policy 플래그를 사용하여 추가 문서 수준 ACL 정책을 제공합니다. 이 플래그는 Document AI Warehouse에서 문서 수준 ACL이 사용 설정된 프로젝트를 위한 것입니다.
문서에 콘텐츠가 포함된 경우 enable_document_text_extraction 플래그를 사용하여 Document AI Warehouse에서 원시 문서의 텍스트를 추출하도록 합니다. 이 플래그는 Document AI 처리와 다르며 문서 추출은 Document AI Warehouse에서 다음 문서 파일 형식만 지원합니다.
- RAW_DOCUMENT_FILE_TYPE_TEXT
- RAW_DOCUMENT_FILE_TYPE_DOCX
folder 필드를 사용하여 인그레스된 문서의 대상 폴더를 지정합니다. 수집된 모든 문서는 지정된 상위 폴더 아래에 연결됩니다.
cloud_function 필드를 사용하여 문서 프로토 파일이 Document AI Warehouse로 이동하기 전에 필드를 추가로 맞춤설정합니다. cloud_function 값은 Document AI Warehouse 서비스 계정에서 액세스할 수 있는 유효한 URL이어야 합니다. 각 통화는 5분 이내에 종료되어야 합니다. 요청과 응답은 JSON 형식입니다. 요청 페이로드에서 다음 키를 찾을 수 있습니다.
- display_name
- properties
- plain_text 또는 cloud_ai_document.text
- reference_id
- document_schema_name
- raw_document_path
- raw_document_file_type
응답 페이로드의 키는 프로토의 일부로 Document AI Warehouse에 수집됩니다. 키가 수정되거나 응답에 추가되면 원래 값이 덮어쓰여집니다. 응답의 추가 키는 삭제됩니다. 해당 값이 유효하지 않으면 문서 수집이 실패합니다.
- display_name
- properties
- plain_text 또는 cloud_ai_document.text
- reference_id
- document_acl_policy
- folder

pipeline_config을 사용하여 파이프라인 맞춤설정을 수집합니다.

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    skip_ingested_documents: "true",
    pipeline_config: {
      enable_document_text_extraction: "true"
      folder: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documents/FOLDER_DOCUMENT_ID",
      cloud_function: "https://REGION-PROJECT_ID.cloudfunctions.net/CLOUD_FUNCTION_NAME"
    }
  }
}

상태 추적

상태 추적은 전체 파이프라인과 각 문서의 수집 결과 진행 상황을 보여줍니다.

LRO가 완료되었는지 확인하여 파이프라인이 완료되었는지 확인할 수 있습니다.
Cloud Storage 메타데이터를 확인하여 파이프라인의 각 문서 상태를 확인할 수 있습니다. Cloud Storage는 각 문서에 다음 키-값 쌍을 만듭니다.
- 키: status; 값: status=queued 또는 status=processed 또는 status=ingested 또는 status=failed
- 키: error; 값: the error message

지원되는 문서 유형

파이프라인에서 지원되는 문서 유형은 Document AI Warehouse에서 지원되는 문서 유형과 동일합니다. 텍스트, PDF, 이미지 (스캔한 PDF, TIFF 파일, JPEG 파일), Microsoft Office 파일 (DOCX, PPTX, XSLX)이 지원됩니다.

Cloud Storage 메타데이터의 문서 속성

파이프라인에서 Cloud Storage 메타데이터를 사용하여 Document AI Warehouse에서 맞춤 속성을 만들 수 있습니다. 키가 스키마의 속성 이름과 일치하는 경우 Cloud Storage 문서의 메타데이터 값이 해당 Document AI Warehouse 문서 속성에 자동으로 복사됩니다.

파이프라인 실행

Cloud Storage 수집 파이프라인에서 다양한 기능을 트리거하려면 다양한 매개변수가 필요합니다. 자세한 내용은 메서드: projects.locations.runPipeline을 참고하세요.

다음 부분에서는 Cloud Storage 수집 파이프라인을 트리거하는 두 가지 예를 제공합니다.

Document AI 프로세서 없이 Cloud Storage 수집 파이프라인을 실행합니다.

REST

curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
"schema_name": "projects/PROJECT_NUMBER/locations/
LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

Document AI 프로세서로 Cloud Storage 수집 파이프라인을 실행합니다.

REST

curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_with_doc_ai_processors_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
            "split_classify_processor_info": {
              "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
            },
            "extract_processor_infos": [
              {
                "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
                "document_type": "DOCUMENT_TYPE",
                "schema_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
              }
            ],
            "processor_results_folder_path": "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME/"
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

이 명령어는 장기 실행 작업의 리소스 이름을 반환합니다. 이 리소스 이름을 사용하여 다음 단계를 따라 파이프라인의 진행 상황을 추적할 수 있습니다.

장기 실행 작업 결과 가져오기

REST

curl --location --request GET 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION' \
--header "Authorization: Bearer ${AUTH_TOKEN}"

다음 단계

수집된 문서를 확인하려면 Document AI Warehouse의 웹 애플리케이션으로 이동하세요.

Cloud Storage 수집 파이프라인 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.