Extensions API

확장 프로그램은 대규모 언어 모델이 외부 데이터에 액세스하고, 계산을 실행하고, 기타 작업을 수행하는 데 필요한 도구입니다. 실시간 데이터를 처리하고 실제 작업을 수행할 수 있습니다. Vertex AI는 확장 프로그램을 등록, 관리, 실행할 수 있는 Extension API를 제공합니다. Vertex AI는 또한 코드 인터프리터 확장 프로그램, Vertex AI Search 확장 프로그램 등 Extension API의 사전 빌드된 확장 프로그램 집합을 제공합니다.

제한사항

  • 'us-central1' 리전에서만 사용할 수 있습니다.

확장 프로그램 가져오기

확장 프로그램 리소스를 만들거나 등록합니다.

구문

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import

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
)

매개변수 목록

매개변수

displayName

선택사항: string

API 및 UI에서 사용자에게 표시되는 확장 프로그램의 표시 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.

description

선택사항: string

API 및 UI에서 사용자에게 표시되는 확장 프로그램에 대한 설명입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.

manifest

JsonDict|ExtensionManifest

확장 프로그램의 매니페스트입니다.

runtimeConfig

선택사항: JsonDict|RuntimeConfig

이 확장 프로그램의 런타임 동작을 제어하는 런타임 구성입니다.

ExtensionManifest

매개변수

name

string

추론을 위해 LLM에 사용되는 확장 프로그램의 이름입니다. 최대 128자의 UTF-8 문자열이어야 합니다.

description

string

LLM에 표시되는 자연어 설명입니다. 확장 프로그램의 사용을 설명해야 하며, LLM이 추론을 수행하는 데 필수적입니다. 최대 1MB의 UTF-8 문자열이어야 합니다.

apiSpec

ApiSpec

추론을 위해 LLM에 표시되는 API 사양입니다. 의미 있고 유용한 설명을 제공해야 합니다.

authConfig

JsonDict|AuthConfig

이 확장 프로그램에서 지원하는 인증 유형입니다.

ApiSpec

ApiSpec에는 OpenAPI yaml 파일을 저장하는 Cloud Storage URI에 대한 참조가 포함됩니다.

"apiSpec": {
  "openApiGcsUri": string
}
매개변수

openApiGcsUri

string
확장 프로그램 API를 설명하는 OpenAPI YAML 파일의 Cloud Storage URI입니다. 예: gs://vertex-extension-public/code_interpreter.yaml

AuthConfig

확장 프로그램 가져오기 요청에는 인증 구성이 포함되어야 합니다.

Google 서비스 계정 인증

코드 인터프리터 확장 프로그램과 Vertex AI Search 확장 프로그램 모두 Vertex AI가 Vertex AI 확장 프로그램 서비스 에이전트를 사용하여 API에 액세스하는 Google 서비스 계정만 지원합니다. Google 서비스 계정 인증을 지원하려면 authConfig를 지정합니다.

"authConfig": {
  "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
  "googleServiceAccountConfig": {
    "serviceAccount": string
  },
}
매개변수

serviceAccount

선택사항: string

확장 프로그램 실행에 사용되는 서비스 계정입니다. 서비스 계정이 지정된 경우 지정된 서비스 계정에 대한 iam.serviceAccounts.getAccessToken 권한을 Vertex AI [확장 프로그램 서비스 에이전트](/vertex-ai/docs/general/access-control#service-agents)에 부여해야 합니다. 지정하지 않으면 Vertex AI 확장 프로그램 서비스 에이전트가 확장 프로그램을 실행하는 데 사용됩니다.

RuntimeConfig

런타임 구성에는 확장 프로그램을 실행할 때 사용되는 추가 구성이 포함되어 있습니다.

코드 인터프리터 확장 프로그램의 경우 runtimeConfig를 다음과 같이 설정할 수 있습니다.

"runtimeConfig": {
   "codeInterpreterRuntimeConfig": {
      "fileInputGcsBucket": string,
      "fileOutputGcsBucket": string
   }
}
매개변수

fileInputGcsBucket

선택사항: string

이 확장 프로그램의 파일 입력에 대한 Cloud Storage 버킷입니다. 지정된 경우 Cloud Storage 버킷의 입력이 지원됩니다. Vertex 확장 프로그램 커스텀 코드 서비스 에이전트에 이 버킷에 대한 roles/storage.objectViewer 권한을 부여해야 합니다. 지정되지 않은 경우 확장 프로그램이 요청 본문의 파일 콘텐츠만 수락하고 Cloud Storage 파일 입력을 거부합니다.

fileOutputGcsBucket

선택사항: string

이 확장 프로그램의 파일 출력에 대한 Cloud Storage 버킷입니다. 지정된 경우 모든 출력 파일이 Cloud Storage 버킷에 기록됩니다. Vertex 확장 프로그램 커스텀 코드 서비스 에이전트에 이 버킷에 대한 roles/storage.objectUser 권한을 부여해야 합니다. 지정되지 않은 경우 파일 콘텐츠가 응답 본문에 출력됩니다.

Vertex AI Search 확장 프로그램의 경우 runtimeConfig를 다음과 같이 설정해야 합니다.

"runtimeConfig": {
  "vertexAiSearchRuntimeConfig": {
    "servingConfigName": string,
  }
}
매개변수

servingConfigName

string

확장 프로그램이 사용할 Vertex AI Search 리소스를 지정하는 Vertex AI Search 서빙 구성 이름입니다. 형식:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

예시

코드 인터프리터 가져오기

이 예시에서는 사용자가 코드 인터프리터 확장 프로그램을 가져오는 방법을 보여줍니다.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Code Interpreter",
    "description": "This extension generates and executes code",
    "manifest": {
      "name": "code_interpreter_tool",
      "description": "Google Code Interpreter Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/code_interpreter.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extension_code_interpreter = extensions.Extension.create(
    display_name = "Code Interpreter",
    description = "This extension generates and executes code in the specified language",
    manifest = {
        "name": "code_interpreter_tool",
        "description": "Google Code Interpreter Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/code_interpreter.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
)

RuntimeConfig와 함께 가져오기

이 예시에서는 사용자가 RuntimeConfig와 함께 확장 프로그램을 가져오는 방법을 보여줍니다(Vertex AI Search 확장 프로그램을 예시로 사용).

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions:import \
 -d '{
    "displayName": "Vertex AI Search extension",
    "description": "A search extension",
    "manifest": {
      "name": "vertex_ai_search",
      "description": "Vertex AI Search Extension",
      "apiSpec": {
        "openApiGcsUri": "gs://vertex-extension-public/vertex_ai_search.yaml",
      },
      "authConfig": {
        "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        "googleServiceAccountConfig": {}
      }
    },
    "runtimeConfig": {
      "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "'${SERVING_CONFIG_NAME}'",
      }
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

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,
        }
    }
)

확장 프로그램 실행

요청에 제공된 매개변수로 확장 프로그램 작업을 직접 호출하는 확장 프로그램을 실행합니다.

구문

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}/:execute

Python

from vertexai.preview import extensions

extension.execute(
  operation_id: str,
  operation_params: Optional[Union[JsonDict, Struct]] = None,
)

매개변수 목록

매개변수

operation_id

string

이 확장 프로그램에서 실행할 작업의 선택된 ID

operation_params

선택사항: JsonDict|Struct

이 작업을 실행하는 데 사용할 요청 매개변수입니다. JSON은 매개변수 이름이 키이고 실제 매개변수 값이 값으로 포함된 맵 형식이어야 합니다. 예: 이 작업에서 'query' 매개변수를 'What is Vertex AI?'로 설정해야 하는 경우 {"query": "What is Vertex AI?"}와 같이 설정할 수 있습니다.

예시

이 예시에서는 코드 인터프리터 확장 프로그램 generate_and_execute를 실행하여 'find the max value in the list: [1,2,3,4,-5]' 쿼리에 대한 답변을 가져옵니다.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}:execute \
 -d '{
   "operation_id": "generate_and_execute",
   "operation_params": {
      "query": "find the max value in the list: [1,2,3,4,-5]",
    }
}'

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

code_interpreter_extensions = extensions.Extension(EXTENSION_ID)
extension_code_interpreter.execute(
    operation_id = "generate_and_execute",
    operation_params = {"query": "find the max value in the list: [1,2,3,4,-5]"},
)

확장 프로그램 나열

프로젝트 내 확장 프로그램 리소스를 나열합니다.

예

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID,location=REGION)

extensions.Extension.list()

확장 프로그램 다운로드

확장 프로그램 리소스를 가져옵니다.

예

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension = extensions.Extension(EXTENSION_ID)

확장 프로그램 업데이트

확장 프로그램 리소스를 업데이트합니다. 확장 프로그램의 displayName, description 또는 toolUseExamples를 업데이트할 수 있습니다.

예

이 예시에서는 확장 프로그램 설명을 'A nice tool'로 업데이트합니다.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

확장 프로그램 삭제

확장 프로그램 리소스를 삭제합니다.

예

이 예시에서는 확장 프로그램 ID와 연결된 확장 프로그램을 삭제합니다.

  • PROJECT_ID = PROJECT_ID
  • REGION = us-central1
  • EXTENSION_ID = EXTENSION_ID

curl

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
http://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/extensions/${EXTENSION_ID}

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=REGION)

extension_code_interpreter = extensions.Extension(
    "${EXTENSION_ID}"
)
extension_code_interpreter.delete()

더 살펴보기

자세한 문서는 다음을 참조하세요.