BigQuery bqutil.procedure.bqml_generate_text 공개 저장 프로시저를 사용하면 ML.GENERATE_TEXT 함수에 대한 일괄 호출을 반복하여 엔드포인트 할당량 및 한도를 초과하지 않고 대규모 데이터 세트를 처리할 수 있습니다. 개별 행에서 함수가 실패하더라도 BigQuery 쿼리 작업이 완료되므로 요청량이 많으면 출력 테이블에 RESOURCE EXHAUSTED 재시도 가능 오류가 남을 수 있습니다. 이 튜토리얼에서는 원격 모델을 만들고 저장 프로시져를 실행하여 공개 뉴스 데이터 세트의 모든 레코드가 처리될 때까지 실패한 행을 반복적으로 재시도합니다.
GitHub에서 저장 프러시저의 소스 코드를 검토하려면 bqml_generate_text.sqlx를 참조하세요.
저장 프러시저 매개변수 및 사용에 대한 자세한 내용은 리드미 파일을 참조하세요.
목표
- BigQuery 데이터 세트를 만듭니다.
gemini-3.5-flash-lite모델을 통해 BigQuery ML 원격 모델을 만듭니다.bqutil.procedure.bqml_generate_text저장 프로시저를 실행하여bigquery-public-data.bbc_news.fulltext공개 데이터 세트에서 텍스트를 반복적으로 생성합니다.- 생성된 텍스트 결과를 확인하고 재시도 가능한 할당량 오류가 남아 있지 않은지 확인합니다.
비용
이 문서에서는 비용이 청구될 수 있는 Google Cloud구성요소를 사용합니다.
- BigQuery ML: You incur costs for the data that you process in BigQuery.
- Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform model.
프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요.
자세한 내용은 BigQuery 가격 책정 및 에이전트 플랫폼 가격 책정을 참조하세요.
시작하기 전에
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
BigQuery, BigQuery Connection, Agent Platform API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기
필요한 역할
이 튜토리얼을 완료하는 데 필요한 권한을 얻으려면 관리자에게 다음의 IAM 역할을 부여해 달라고 요청하세요.
-
BigQuery 데이터 세트, 연결, 모델 만들기 및 사용: 프로젝트의 BigQuery 관리자(
roles/bigquery.admin) -
연결의 서비스 계정에 권한 부여: 프로젝트에 대한 프로젝트 IAM 관리자(
roles/resourcemanager.projectIamAdmin)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이러한 사전 정의된 역할에는 이 튜토리얼을 완료하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
이 튜토리얼을 완료하려면 다음 권한이 필요합니다.
-
데이터 세트 만들기:
bigquery.datasets.create -
연결을 만들고, 위임하고, 사용하기:
bigquery.connections.* -
기본 연결 설정:
bigquery.config.* -
서비스 계정 권한 설정:
-
resourcemanager.projects.getIamPolicy -
resourcemanager.projects.setIamPolicy
-
-
모델을 만들고 추론을 실행하기:
-
bigquery.jobs.create -
bigquery.models.create -
bigquery.models.getData -
bigquery.models.updateData -
bigquery.models.updateMetadata
-
데이터 세트 만들기
BigQuery 데이터 세트를 만들려면 다음 옵션 중 하나를 선택합니다.
콘솔
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
왼쪽 창에서 탐색기를 클릭합니다.
왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다.
탐색기에서 프로젝트를 펼친 후 데이터 세트를 클릭합니다.
데이터 세트 페이지에서 데이터 세트 만들기를 클릭합니다.
데이터 세트 만들기 창에서 다음을 수행합니다.
데이터 세트 ID에
bqml_tutorial를 입력합니다.데이터 위치로 미국을 선택합니다.
나머지 기본 설정은 그대로 둡니다.
데이터 세트 만들기를 클릭합니다.
bq
새 데이터 세트를 만들려면 bq mk --dataset 명령어를 사용합니다.
데이터 위치가
US로 설정된bqml_tutorial데이터 세트를 만듭니다.bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
데이터 세트가 생성되었는지 확인합니다.
bq ls
API
데이터 세트 리소스가 정의된 datasets.insert 메서드를 호출합니다.
{ "datasetReference": { "datasetId": "bqml_tutorial" } }
원격 모델 만들기
CREATE MODEL 문을 사용하여 호스팅된 Agent Platform gemini-3.5-flash-lite 모델을 나타내는 원격 모델을 만듭니다.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
쿼리 편집기에서 다음 쿼리를 실행합니다.
CREATE OR REPLACE MODEL `bqml_tutorial.generate_text` REMOTE WITH CONNECTION DEFAULT OPTIONS (ENDPOINT = 'gemini-3.5-flash-lite');
쿼리가 완료되는 데 몇 초 정도 걸리며 그 이후에는
generate_text모델이 탐색기 창의bqml_tutorial데이터 세트에 표시됩니다. 이 쿼리에서는CREATE MODEL문을 사용하여 모델을 만들므로 쿼리 결과가 없습니다.
저장 프러시저 실행
CALL 문을 사용하여 bqutil.procedure.bqml_generate_text 저장 프로시저를 실행합니다. 이 저장 프로시저는 bqml_tutorial.generate_text 모델과 bigquery-public-data.bbc_news.fulltext 공개 테이블을 사용하여 ML.GENERATE_TEXT 함수 호출을 반복합니다.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
쿼리 편집기에서 다음 쿼리를 실행합니다.
CALL `bqutil.procedure.bqml_generate_text`( "bigquery-public-data.bbc_news.fulltext", -- source table "PROJECT_ID.bqml_tutorial.news_generated_text", -- destination table "PROJECT_ID.bqml_tutorial.generate_text", -- model "body", -- prompt column ["filename"], -- key columns '{"flatten_json_output": true}' -- optional arguments );
PROJECT_ID를 프로젝트 ID로 바꿉니다.저장 프로시저는
ML.GENERATE_TEXT함수의 출력을 포함하는bqml_tutorial.news_generated_text테이블을 만듭니다.쿼리 실행이 완료되면
bqml_tutorial.news_generated_text테이블에 재시도 가능한 오류가 포함된 행이 없는지 확인합니다. 쿼리 편집기에서 다음 문을 실행합니다.SELECT * FROM `bqml_tutorial.news_generated_text` WHERE ml_generate_text_status LIKE '%A retryable error occurred%';
쿼리가
There is no data to display메시지를 반환합니다.쿼리 편집기에서 다음 문을 실행하여 생성된 텍스트 결과의 샘플을 검사합니다.
SELECT filename, prompt, ml_generate_text_llm_result, ml_generate_text_status FROM `bqml_tutorial.news_generated_text` LIMIT 3;
출력은 다음과 비슷합니다.
+------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+ | filename | prompt | ml_generate_text_llm_result | ml_generate_text_status | +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+ | bbc/tech/209.txt | A 20-year-old US man is selling... | It looks like you shared a news article about Andrew... | | | bbc/business/375.txt | South Korea's largest credit card... | It looks like you shared a news article about the 2004... | | | bbc/sport/139.txt | A brave defensive display, led by... | It looks like you have shared a match report from a... | | +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
삭제
이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.
프로젝트 삭제
Google Cloud 프로젝트 삭제:
gcloud projects delete PROJECT_ID
개별 리소스 삭제
프로젝트를 재사용하려면 이 튜토리얼에서 만든 리소스를 삭제합니다.
콘솔
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
bqml_tutorial데이터 세트를 삭제합니다. 데이터 세트를 삭제하면 원격 모델과 출력 테이블도 삭제됩니다.탐색기 창에서 프로젝트를 펼치고 데이터 세트를 클릭합니다.
데이터 세트 목록에서
bqml_tutorial데이터 세트를 클릭합니다.세부정보 창에서 삭제를 클릭합니다.
데이터 세트 삭제 대화상자에서 삭제를 클릭합니다.
bq
bqml_tutorial 데이터 세트, 원격 모델, 출력 테이블을 삭제합니다.
bq rm --dataset --recursive bqml_tutorial
다음 단계
ML.GENERATE_TEXT함수 및AI.GENERATE_TEXT함수에 대해 자세히 알아보세요.- BigQuery의 생성형 AI에 대해 자세히 알아보세요.
- 텍스트 생성 함수를 선택하는 방법 알아보기