調整 API

模型調整是重要的程序,可讓 Gemini 更精準地執行特定工作。模型調整的運作方式是為模型提供訓練資料集,資料集內有一組特定下游任務的範例。

在下列情況下使用 Gemini 調整 API:

支援的機型:

您可以在下列 Gemini 模型上使用監督式微調:

也支援 Translation LLM V2 (translation-llm-002)。

語法範例

調整模型的語法。

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs \
-d '{
  "baseModel": "...",
  "supervisedTuningSpec" : {
    ...
      "hyper_parameters": {
        ...
      },
  },
  "tunedModelDisplayName": "",
}'

參數清單

如需實作詳情,請參閱範例

要求主體

要求主體包含下列參數的資料:

參數

source_model

自由參加:string

要調整的基礎模型名稱。

tunedModelDisplayName

string

TunedModel 的顯示名稱。名稱長度上限為 128 個字元,可以使用任何 UTF-8 字元。

supervisedTuningSpec

參數

training_dataset

string

訓練資料集的 Cloud Storage URI。資料集必須採用 JSONL 檔案格式。為獲得最佳結果,請提供至少 100 到 500 個範例。詳情請參閱「 關於監督式微調資料集」。

validation_dataset

自由參加:string

驗證資料集的 Cloud Storage URI。資料集必須採用 JSONL 檔案格式。資料集最多可包含 256 個樣本。如果您提供這個檔案,系統會在微調期間定期使用資料產生驗證指標。 詳情請參閱「 關於監督式微調資料集 」。

epoch_count

自由參加:int

模型在訓練期間完整通過整個訓練資料集的次數。Vertex AI 會根據訓練資料集大小自動調整預設值。這個值是根據基準化結果計算得出,可協助您提升模型輸出內容的品質。

learning_rate_multiplier

自由參加:float

用於調整預設學習率的調節係數。

adapter_size

自由參加:AdapterSize

用於調整的轉接器大小。

tuned_model_display_name

自由參加:string

TunedModel 的顯示名稱。名稱長度上限為 128 個字元,可以使用任何 UTF-8 字元。

AdapterSize

調整工作的轉接器大小。

參數

ADAPTER_SIZE_UNSPECIFIED

未指定轉接器大小。

ADAPTER_SIZE_ONE

轉接器大小 1。

ADAPTER_SIZE_FOUR

轉接器大小 4。

ADAPTER_SIZE_EIGHT

轉接器大小 8。

ADAPTER_SIZE_SIXTEEN

轉接器大小 16。

範例

建立受監督的調整工作

您可以透過 Vertex AI SDK for Python 或傳送 POST 要求,建立監督式文字模型微調工作。

基本用途

基本用途只會為 baseModeltraining_dataset_uri 設定值。其他參數則使用預設值。

REST

如要建立模型微調作業,請使用 tuningJobs.create 方法傳送 POST 要求。請注意,部分模型不支援某些參數。請務必只加入要調整模型的適用參數。

使用任何要求資料之前,請先替換以下項目:

  • PROJECT_ID:您的專案 ID
  • TUNING_JOB_REGION:執行微調工作的區域。這也是上傳微調模型的預設區域。
  • BASE_MODEL:要微調的基礎模型名稱。
  • TRAINING_DATASET_URI:訓練資料集的 Cloud Storage URI。資料集必須採用 JSONL 檔案格式。為獲得最佳結果,請提供至少 100 到 500 個範例。詳情請參閱「關於監督式微調資料集 」。

HTTP 方法和網址:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

JSON 要求主體:

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "training_dataset_uri": "TRAINING_DATASET_URI"
  },
}

如要傳送要求,請選擇以下其中一個選項:

curl

將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

Python


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

進階用途

進階用途是基本用途的擴展,但也會為選用 hyper_parameters 設定值,例如 epoch_countlearning_rate_multiplieradapter_size

REST

如要建立模型微調作業,請使用 tuningJobs.create 方法傳送 POST 要求。請注意,部分模型不支援某些參數。請務必只加入要調整模型的適用參數。

使用任何要求資料之前,請先替換以下項目:

  • PROJECT_ID:您的專案 ID。
  • TUNING_JOB_REGION:執行微調工作的區域。這也是上傳微調模型的預設區域。
  • BASE_MODEL:要微調的基礎模型名稱。
  • TRAINING_DATASET_URI:訓練資料集的 Cloud Storage URI。資料集必須採用 JSONL 檔案格式。為獲得最佳結果,請提供至少 100 到 500 個範例。詳情請參閱「關於監督式微調資料集 」。
  • VALIDATION_DATASET_URI選用:驗證資料集檔案的 Cloud Storage URI。
  • EPOCH_COUNT選用:模型在訓練期間完整通過整個訓練資料集的次數。如未設定,系統會使用預先填入的建議值
  • ADAPTER_SIZE選填:用於微調工作的轉接程式大小。轉接器大小會影響調整工作的可訓練參數數量。轉接器越大,模型就能學習更複雜的工作,但需要更大的訓練資料集和更長的訓練時間。
  • LEARNING_RATE_MULTIPLIER:選用:要套用至建議學習率的調節係數。如要使用建議值,請將此欄位留空。
  • EXPORT_LAST_CHECKPOINT_ONLY選用:設為 true,只使用最新的檢查點。
  • METRIC_SPEC選用:您使用的一或多個指標規格,可透過 Gen AI 評估服務執行評估。您可以使用下列指標規格: "pointwise_metric_spec""pairwise_metric_spec"
  • METRIC_SPEC_FIELD_NAME選用:所選指標規格的必填欄位。例如 "metric_prompt_template"
  • METRIC_SPEC_FIELD_NAME_CONTENT選用:所選指標規格的欄位內容。舉例來說,您可以針對逐點評估使用下列欄位內容:"Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • CLOUD_STORAGE_BUCKET選用:Cloud Storage bucket,用於儲存 Gen AI Evaluation Service 執行的評估結果。
  • TUNED_MODEL_DISPLAYNAME選用:微調後模型的顯示名稱。如未設定,系統會產生隨機名稱。
  • KMS_KEY_NAME選用:用來保護資源的客戶管理加密金鑰的 Cloud KMS 資源 ID。金鑰格式為 projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key。金鑰必須與運算資源的建立位置位於相同區域。詳情請參閱客戶管理的加密金鑰 (CMEK)
  • SERVICE_ACCOUNT選用:tuningJob 工作負載執行的服務帳戶。如未指定,則會使用專案中的 Vertex AI 安全微調服務代理。請參閱「調整服務代理程式」。如要使用客戶管理的服務帳戶,請務必將 roles/aiplatform.tuningServiceAgent 角色授予該服務帳戶。此外,請將 Tuning Service Agent roles/iam.serviceAccountTokenCreator 角色指派給客戶管理的服務帳戶。

HTTP 方法和網址:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

JSON 要求主體:

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "trainingDatasetUri": "TRAINING_DATASET_URI",
      "validationDatasetUri": "VALIDATION_DATASET_URI",
      "hyperParameters": {
          "epochCount": "EPOCH_COUNT",
          "adapterSize": "ADAPTER_SIZE",
          "learningRateMultiplier": "LEARNING_RATE_MULTIPLIER"
      },
      "exportLastCheckpointOnly": EXPORT_LAST_CHECKPOINT_ONLY,
      "evaluationConfig": {
          "metrics": [
              {
                  "aggregation_metrics": ["AVERAGE", "STANDARD_DEVIATION"],
                  "METRIC_SPEC": {
                      "METRIC_SPEC_FIELD_NAME":
                          METRIC_SPEC_FIELD_CONTENT
                  }
              },
          ],
          "outputConfig": {
              "gcs_destination": {
                  "output_uri_prefix": "CLOUD_STORAGE_BUCKET"
              }
          },
      },
  },
  "tunedModelDisplayName": "TUNED_MODEL_DISPLAYNAME",
  "encryptionSpec": {
    "kmsKeyName": "KMS_KEY_NAME"
  },
  "serviceAccount": "SERVICE_ACCOUNT"
}

如要傳送要求,請選擇以下其中一個選項:

curl

將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

Python


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Initialize Vertex AI with your service account for BYOSA (Bring Your Own Service Account).
# Uncomment the following and replace "your-service-account"
# vertexai.init(service_account="your-service-account")

# Initialize Vertex AI with your CMEK (Customer-Managed Encryption Key).
# Un-comment the following line and replace "your-kms-key"
# vertexai.init(encryption_spec_key_name="your-kms-key")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
    # The following parameters are optional
    validation_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_validation_data.jsonl",
    tuned_model_display_name="tuned_gemini_2_0_flash",
    # Advanced use only below. It is recommended to use auto-selection and leave them unset
    # epochs=4,
    # adapter_size=4,
    # learning_rate_multiplier=1.0,
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

列出調整工作

您可以使用 Vertex AI SDK for Python 或傳送 GET 要求,查看目前專案的微調工作清單。

REST

如要建立模型微調作業,請使用 tuningJobs.create 方法傳送 POST 要求。請注意,部分模型不支援某些參數。請務必只加入要調整模型的適用參數。

使用任何要求資料之前,請先替換以下項目:

  • PROJECT_ID:。
  • TUNING_JOB_REGION:執行微調工作的區域。這也是上傳微調模型的預設區域。

HTTP 方法和網址:

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

執行下列指令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

responses = sft.SupervisedTuningJob.list()

for response in responses:
    print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7c85287b2680>
# resource name: projects/12345678/locations/us-central1/tuningJobs/123456789012345

取得調整工作的詳細資料

您可以使用 Python 適用的 Vertex AI SDK 或傳送 GET 要求,取得微調工作的詳細資料。

REST

如要查看模型微調作業清單,請使用 tuningJobs.get 方法傳送 GET 要求,並指定 TuningJob_ID

使用任何要求資料之前,請先替換以下項目:

  • PROJECT_ID:。
  • TUNING_JOB_REGION:執行微調工作的區域。這也是上傳微調模型的預設區域。
  • TUNING_JOB_ID:微調作業的 ID。

HTTP 方法和網址:

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID"

PowerShell

執行下列指令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
response = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)

print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7cc4bb20baf0>
# resource name: projects/1234567890/locations/us-central1/tuningJobs/4982013113894174720

取消微調工作

您可以使用 Python 適用的 Vertex AI SDK 或傳送 POST 要求,取消微調工作。

REST

如要查看模型微調作業清單,請使用 tuningJobs.cancel 方法傳送 GET 要求,並指定 TuningJob_ID

使用任何要求資料之前,請先替換以下項目:

  • PROJECT_ID:。
  • TUNING_JOB_REGION:執行微調工作的區域。這也是上傳微調模型的預設區域。
  • TUNING_JOB_ID:微調作業的 ID。

HTTP 方法和網址:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel"

PowerShell

執行下列指令:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel" | Select-Object -Expand Content

您應該會收到類似如下的 JSON 回應。

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
job = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)
job.cancel()

後續步驟

如需詳細說明文件,請參閱下列內容: