Vertex AI는 확장 프로그램을 등록, 관리, 실행할 수 있는 Extension API를 제공합니다. Vertex AI는 또한 코드 인터프리터 확장 프로그램, Vertex AI Search 확장 프로그램 등 Extension API의 사전 빌드된 확장 프로그램 집합을 제공합니다.
제한사항
Extension API는 us-central1
리전에서만 사용할 수 있습니다.
예시 구문
확장 프로그램 리소스를 만드는 구문입니다.
curl
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/extensions:import \ -d '{ "displayName": "...", "description": "...", "manifest": { ... "apiSpec": { ... }, "authConfig": { ... } ... } }'
Python
from vertexai.preview import extensions extensions.Extension.create( manifest: Union[JsonDict, ExtensionManifest], display_name: Optional[str] = None, description: Optional[str] = None, runtime_config: Optional[Union[JsonDict, RuntimeConfig]] = None )
매개변수 목록
요청 본문
매개변수 | |
---|---|
|
선택사항: API 및 UI에서 사용자에게 표시되는 확장 프로그램의 표시 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다. |
|
선택사항: API 및 UI에서 사용자에게 표시되는 확장 프로그램에 대한 설명입니다. 최대 1MB의 UTF-8 문자열이어야 합니다. |
확장 프로그램의 매니페스트입니다. |
|
선택사항: 확장 프로그램의 런타임 동작을 제어하는 런타임 구성입니다. 코드 인터프리터 확장 프로그램의 형식은 다음과 같습니다. "runtimeConfig": { "codeInterpreterRuntimeConfig": { "fileInputGcsBucket": string, "fileOutputGcsBucket": string } } Vertex AI Search 확장 프로그램의 형식은 다음과 같습니다. "runtimeConfig": { "vertexAiSearchRuntimeConfig": { "servingConfigName": string, } } |
manifest
확장 프로그램의 매니페스트입니다.
매개변수 | |
---|---|
|
추론을 위해 LLM에 사용되는 확장 프로그램의 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다. |
|
확장 프로그램 사용에 대한 자연어 설명입니다. 추론을 수행하는 데 도움이 되도록 LLM에 설명이 표시됩니다. 최대 1MB의 UTF-8 문자열이어야 합니다. |
추론을 위해 LLM에 표시되는 API 사양입니다. 의미 있고 유용한 설명을 제공해야 합니다. "apiSpec": { "openApiGcsUri": string } |
|
이 확장 프로그램에서 지원하는 인증 유형입니다. 확장 프로그램 가져오기 요청에는 인증 구성이 포함되어야 합니다. "authConfig": { "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH", "googleServiceAccountConfig": { "serviceAccount": string }, } |
apiSpec
추론을 위해 LLM에 표시되는 API 사양입니다.
매개변수 | |
---|---|
|
확장 프로그램 API를 설명하는 OpenAPI YAML 파일의 Cloud Storage URI입니다(예: |
authConfig
이 확장 프로그램에서 지원하는 인증 유형입니다.
매개변수 | |
---|---|
|
인증 방법입니다. 지원되는 값: |
googleServiceAccountConfig
코드 인터프리터 확장 프로그램과 Vertex AI Search 확장 프로그램은 Vertex AI가 Vertex AI 확장 프로그램 서비스 에이전트를 사용하여 API에 액세스하는 Google 서비스 계정 인증만 지원합니다.
매개변수 | |
---|---|
|
선택사항: 확장 프로그램 실행에 사용되는 서비스 계정입니다. 서비스 계정이 지정된 경우 지정된 서비스 계정에 대한 |
runtimeConfig
runtimeConfig
객체에는 확장 프로그램을 실행할 때 사용되는 추가 구성이 포함됩니다.
코드 인터프리터 확장 프로그램
매개변수 | |
---|---|
|
선택사항: 확장 프로그램에 대한 파일 입력을 위한 Cloud Storage 버킷입니다. Vertex 확장 프로그램 커스텀 코드 서비스 에이전트에 이 버킷에 대한 |
|
선택사항: 확장 프로그램의 파일 출력에 대한 Cloud Storage 버킷입니다. Vertex 확장 프로그램 커스텀 코드 서비스 에이전트에 이 버킷에 대한 |
Vertex AI Search 확장 프로그램
매개변수 | |
---|---|
|
확장 프로그램이 사용할 Vertex AI Search 리소스를 지정하는 Vertex AI Search 서빙 구성 이름입니다. 형식:
|
확장 프로그램 실행
매개변수 | |
---|---|
|
이 확장 프로그램에서 실행할 작업의 선택된 ID입니다. |
|
선택사항: 이 작업을 실행하는 데 사용할 요청 매개변수입니다. JSON은 매개변수 이름이 키이고 실제 매개변수 값이 값으로 포함된 맵 형식이어야 합니다. 예를 들어 |
예시
코드 인터프리터 확장 프로그램 가져오기
확장 프로그램 리소스를 만들거나 등록합니다.
이 예시에서는 코드 인터프리터 확장 프로그램을 가져오는 방법을 보여줍니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- DISPLAY_NAME: API 및 UI에서 사용자에게 표시되는 확장 프로그램의 표시 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.
- DESCRIPTION: API 및 UI에서 사용자에게 표시되는 확장 프로그램에 대한 설명입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.
- MANIFEST_NAME: 추론을 위해 LLM에 사용되는 확장 프로그램의 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.
- MANIFEST_DESCRIPTION: LLM에 표시되는 자연어 설명입니다. 확장 프로그램의 사용을 설명해야 하며, LLM이 추론을 수행하는 데 필수적입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.
- GCS_URI: 확장 프로그램 API를 설명하는 OpenAPI YAML 파일의 Cloud Storage URI입니다.
- AUTH_TYPE: 인증 방법입니다. 지원되는 값:
GOOGLE_SERVICE_ACCOUNT_AUTH
.
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
JSON 요청 본문:
{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "manifest": { "name": "NAME", "description": "MANIFEST_DESCRIPTION", "apiSpec": { "openApiGcsUri": "GCS_URI", }, "authConfig": { "authType": "AUTH_TYPE", "googleServiceAccountConfig": {} } } }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content
Python
Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
런타임 구성으로 가져오기
확장 프로그램 리소스를 만들거나 등록합니다.
이 예시에서는 RuntimeConfig
를 지정하여 Vertex AI Search 확장 프로그램을 가져오는 방법을 보여줍니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- DISPLAY_NAME: API 및 UI에서 사용자에게 표시되는 확장 프로그램의 표시 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.
- DESCRIPTION: API 및 UI에서 사용자에게 표시되는 확장 프로그램에 대한 설명입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.
- MANIFEST_NAME: 추론을 위해 LLM에 사용되는 확장 프로그램의 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.
- MANIFEST_DESCRIPTION: LLM에 표시되는 자연어 설명입니다. 확장 프로그램의 사용을 설명해야 하며, LLM이 추론을 수행하는 데 필수적입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.
- GCS_URI: 확장 프로그램 API를 설명하는 OpenAPI YAML 파일의 Cloud Storage URI입니다.
- AUTH_TYPE: 인증 방법입니다. 지원되는 값:
GOOGLE_SERVICE_ACCOUNT_AUTH
. - SERVING_CONFIG_NAME: 확장 프로그램이 사용할 Vertex AI Search 리소스를 지정하는 Vertex AI Search 서빙 구성 이름입니다. 형식:
projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import
JSON 요청 본문:
{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "manifest": { "name": "NAME", "description": "MANIFEST_DESCRIPTION", "apiSpec": { "openApiGcsUri": "GCS_URI", }, "authConfig": { "authType": "AUTH_TYPE", "googleServiceAccountConfig": {} }, runtime_config={ "vertex_ai_search_runtime_config": { "serving_config_name": SERVING_CONFIG_NAME, } } } }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import"
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content
Python
import vertexai from vertexai.preview import extensions vertexai.init(project=PROJECT_ID, location=LOCATION) extension_vertex_ai_search = extensions.Extension.create( display_name = "vertex_ai_search", description = "This extension search from provided datastore", manifest = { "name": "vertex_ai_search", "description": "Google Vertex AI Search Extension", "api_spec": { "open_api_gcs_uri": "gs://vertex-extension-public/vertex_ai_search.yaml" }, "auth_config": { "google_service_account_config": {}, "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH", }, }, runtime_config={ "vertex_ai_search_runtime_config": { "serving_config_name": SERVING_CONFIG_NAME, } } )
확장 프로그램 실행
확장 프로그램을 실행하려면 확장 프로그램을 직접 호출하고 요청에 실행 매개변수를 제공합니다.
이 예시에서는 코드 인터프리터 확장 프로그램 generate_and_execute
를 실행하여 find the max value in the list: [1,2,3,4,-5]
쿼리에 대한 답변을 가져옵니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- EXTENSION_ID: 확장 프로그램의 ID입니다.
- OPERATION_ID: 이 확장 프로그램에서 실행할 작업의 선택된 ID입니다.
- QUERY: 작업을 실행할 요청 매개변수로, 키-값 형식입니다(
{"query": "What is Vertex AI?"}.
).
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute
JSON 요청 본문:
{ "operation_id": "OPERATION_ID", "operation_params": { "query": "QUERY", } }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute"
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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
Python
Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
확장 프로그램 나열
프로젝트의 확장 프로그램을 나열합니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- EXTENSION_ID: 확장 프로그램의 ID입니다.
HTTP 메서드 및 URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
다음 명령어를 실행합니다.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"
PowerShell
다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions" | Select-Object -Expand Content
Python
Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
확장 프로그램 가져오기
확장 프로그램의 세부정보를 가져옵니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- EXTENSION_ID: 확장 프로그램의 ID입니다.
HTTP 메서드 및 URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
다음 명령어를 실행합니다.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"
PowerShell
다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content
Python
Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
확장 프로그램 업데이트
확장 프로그램을 업데이트합니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- EXTENSION_ID: 확장 프로그램의 ID입니다.
- UPDATE_MASK: 업데이트할 매개변수입니다. 허용되는 값은
displayName
,description
,toolUseExamples
입니다.
HTTP 메서드 및 URL:
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"
JSON 요청 본문:
{ "description": "UPDATE_MASK", }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK""
PowerShell
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"" | Select-Object -Expand Content
확장 프로그램 삭제
확장 프로그램을 삭제합니다.
이 예시에서는 확장 프로그램 ID와 연결된 확장 프로그램을 삭제합니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- LOCATION: 요청을 처리하는 리전입니다.
- EXTENSION_ID: 확장 프로그램의 ID입니다.
HTTP 메서드 및 URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
다음 명령어를 실행합니다.
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"
PowerShell
다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content
Python
Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.