REST Resource: projects.locations.collections.engines

리소스: Engine

Engine의 학습 및 서빙 파라미터를 설명하는 메타데이터입니다.

JSON 표현 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "dataStoreIds": [
    string
  ],
  "solutionType": enum (SolutionType),
  "industryVertical": enum (IndustryVertical),
  "commonConfig": {
    object (CommonConfig)
  },
  "appType": enum (AppType),
  "disableAnalytics": boolean,
  "features": {
    string: enum (FeatureState),
    ...
  },
  "cmekConfig": {
    object (CmekConfig)
  },
  "configurableBillingApproach": enum (ConfigurableBillingApproach),
  "modelConfigs": {
    string: enum (ModelState),
    ...
  },

  // Union field engine_config can be only one of the following:
  "chatEngineConfig": {
    object (ChatEngineConfig)
  },
  "searchEngineConfig": {
    object (SearchEngineConfig)
  },
  "mediaRecommendationEngineConfig": {
    object (MediaRecommendationEngineConfig)
  }
  // End of list of possible types for union field engine_config.

  // Union field engine_metadata can be only one of the following:
  "chatEngineMetadata": {
    object (ChatEngineMetadata)
  }
  // End of list of possible types for union field engine_metadata.
}
필드
name

string

변경할 수 없습니다. 식별자. 엔진의 정규화된 리소스 이름을 나타냅니다.

이 필드는 길이 제한이 1,024자(영문 기준)인 UTF-8로 인코딩된 문자열이어야 합니다.

형식: projects/{project}/locations/{location}/collections/{collection}/engines/{engine} 엔진은 길이가 1~63자여야 하며, 유효한 문자는 /[a-z0-9][a-z0-9-_]*/입니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
displayName

string

필수 항목. 엔진의 표시 이름입니다. 인간이 읽을 수 있는 형태여야 합니다. 길이 제한이 1,024자(영문 기준)인 UTF-8로 인코딩된 문자열입니다.
createTime

string (Timestamp format)

출력 전용입니다. 추천 엔진이 생성된 시각의 타임스탬프를 나타냅니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
updateTime

string (Timestamp format)

출력 전용입니다. 추천 엔진이 마지막으로 업데이트된 시각의 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
dataStoreIds[]

string

선택사항. 이 엔진과 연결된 데이터 스토어입니다.

SOLUTION_TYPE_SEARCH 및 SOLUTION_TYPE_RECOMMENDATION 유형의 엔진은 최대 하나의 데이터 스토어와만 연결할 수 있습니다.

solutionType이 SOLUTION_TYPE_CHAT인 경우 동일한 Collection 내에 있는 여러 DataStore를 여기에 연결할 수 있습니다.

CreateEngineRequest에서 사용되는 이 필드를 사용하는 경우, 시스템이 필요한 초기화를 수행할 수 있도록 최소 하나의 DataStore ID를 제공해야 합니다.
solutionType

enum (SolutionType)

필수 항목. 엔진의 솔루션입니다.
industryVertical

enum (IndustryVertical)

선택사항. 엔진이 등록되는 업종 카테고리입니다. 엔진 업종 카테고리는 연결된 DataStore를 기준으로 제한되며, 엔진에 설정된 업종은 엔진에 연결된 데이터 스토어의 업종과 일치해야 합니다.
commonConfig

object (CommonConfig)

엔진의 메타데이터를 지정하는 공통 구성 사양입니다.
appType

enum (AppType)

선택사항. 변경할 수 없습니다. 이 엔진 리소스가 나타내는 애플리케이션 유형입니다. 참고: 이는 기존 업종 카테고리 또는 솔루션 유형과 무관한 새로운 개념입니다.
disableAnalytics

boolean

선택사항. 이 엔진에서 수행되는 검색에 대해 분석을 사용 중지할지 여부입니다.
features

map (key: string, value: enum (FeatureState))

선택사항. 엔진이 특정 기능을 사용하거나 사용하지 않도록 설정하는 기능 구성입니다. 지원되는 키는 다음과 같습니다.

  • *: 모든 기능. 이 키가 설정되어 있으면 다른 모든 기능 상태 설정은 무시됩니다.
  • agent-gallery
  • no-code-agent-builder
  • prompt-gallery
  • model-selector
  • notebook-lm
  • people-search
  • people-search-org-chart
  • bi-directional-audio
  • feedback
  • session-sharing
  • personalization-memory
  • disable-agent-sharing
  • disable-image-generation
  • disable-video-generation
  • disable-onedrive-upload
  • disable-talk-to-content
  • disable-google-drive-upload
cmekConfig

object (CmekConfig)

출력 전용입니다. 엔진에 대한 CMEK 관련 정보를 포함합니다.
configurableBillingApproach

enum (ConfigurableBillingApproach)

선택사항. 구성 가능한 결제 방식에 대한 설정입니다.
modelConfigs

map (key: string, value: enum (ModelState))

선택사항. 모델 이름을 이 엔진에 대한 해당 모델의 개별 구성에 매핑합니다. 이를 통해 관리자 사용자는 개별 모델을 사용 설정하거나 사용 중지할 수 있습니다. 여기에는 관리자가 상태를 재정의한 모델만 저장됩니다.

상태가 지정되지 않았거나, 특정 모델에 대해 modelConfigs가 비어 있는 경우, 해당 모델을 사용할 수 있을지 여부는 시스템이 기본 구성에 따라 결정합니다. 예를 들어 미리보기 모델은 관리자가 사용하도록 설정하지 않았다면 기본적으로 사용 중지되어야 합니다.
통합 필드 engine_config. 엔진의 동작을 정의하는 추가 구성 사양입니다. engine_config는 다음 중 하나여야 합니다.
chatEngineConfig

object (ChatEngineConfig)

Chat Engine에 대한 구성입니다. solutionType이 SOLUTION_TYPE_CHAT인 경우에만 적용됩니다.
searchEngineConfig

object (SearchEngineConfig)

검색 엔진에 대한 구성입니다. solutionType이 SOLUTION_TYPE_SEARCH인 경우에만 적용됩니다.
mediaRecommendationEngineConfig

object (MediaRecommendationEngineConfig)

미디어 엔진에 대한 구성입니다. solutionType이 SOLUTION_TYPE_RECOMMENDATION이고, IndustryVertical.MEDIA 업종인 데이터 스토어에만 적용됩니다.
통합 필드 engine_metadata. 엔진 상태를 모니터링하기 위한 엔진 메타데이터입니다. engine_metadata는 다음 중 하나여야 합니다.
chatEngineMetadata

object (ChatEngineMetadata)

출력 전용입니다. 채팅 엔진에 대한 추가 정보를 제공합니다. solutionType이 SOLUTION_TYPE_CHAT인 경우에만 적용됩니다.

ChatEngineConfig

채팅 엔진에 대한 구성입니다.

JSON 표현 
{
  "agentCreationConfig": {
    object (AgentCreationConfig)
  },
  "dialogflowAgentToLink": string,
  "allowCrossRegion": boolean
}
필드
agentCreationConfig

object (AgentCreationConfig)

이 엔진과 연결되는 Dialogflow 에이전트를 생성하기 위한 구성입니다.

이 구성은 엔진 생성 시 한 번만 Dialogflow 서비스로 전달되어 사용됩니다. 즉, 엔진 생성 이후에는 EngineService.GetEngine 또는 EngineService.ListEngines API를 사용하여 조회할 수 없습니다.
allowCrossRegion

boolean

선택사항. 이 플래그를 true로 설정하면 에이전트와 엔진이 서로 다른 위치에 존재하는 것을 허용합니다. 그렇지 않으면 에이전트와 엔진은 반드시 동일한 위치에 있어야 합니다. 이 플래그는 기본적으로 false로 설정됩니다.

allowCrossRegion은 EngineService.CreateEngine 호출 시 한 번만 전달되어 사용됩니다. 즉, 엔진 생성 이후에는 EngineService.GetEngine 또는 EngineService.ListEngines API를 사용하여 조회할 수 없습니다.

AgentCreationConfig

Dialogflow 에이전트를 생성하기 위한 구성입니다.

이 구성은 엔진 생성 시 한 번만 Dialogflow 서비스로 전달되어 사용됩니다. 즉, 엔진 생성 이후에는 EngineService.GetEngine 또는 EngineService.ListEngines API를 사용하여 조회할 수 없습니다.

JSON 표현 
{
  "business": string,
  "defaultLanguageCode": string,
  "timeZone": string,
  "location": string
}
필드
business

string

에이전트가 대표하는 회사, 조직 또는 기타 항목의 이름입니다. 이 값은 지식 커넥터 LLM 프롬프트 및 지식 검색에 사용됩니다.
defaultLanguageCode

string

필수 항목. 에이전트 기본 언어로, 언어 태그로 사용됩니다. 현재 지원되는 언어 코드 목록은 언어 지원을 참조하세요.
timeZone

string

필수 항목. 시간대 데이터베이스의 에이전트 시간대입니다(예: America/New_York, Europe/Paris).
location

string

에이전트 생성 시 사용할 에이전트 위치입니다. 지원되는 값은 global/us/eu입니다. 이 값을 지정하지 않으면, us 리전의 엔진은 기본적으로 us-central-1에, eu 리전의 엔진은 기본적으로 eu-west-1에 에이전트를 생성합니다.

SearchEngineConfig

검색 엔진에 대한 구성입니다.

JSON 표현 
{
  "searchTier": enum (SearchTier),
  "searchAddOns": [
    enum (SearchAddOn)
  ]
}
필드
searchTier

enum (SearchTier)

이 엔진이 사용하는 검색 기능 등급입니다.

등급에 따라 가격 책정이 달라질 수 있습니다. 자세한 내용은 가격 책정 문서를 참조하세요.

지정하지 않을 경우 기본값은 SearchTier.SEARCH_TIER_STANDARD입니다.
searchAddOns[]

enum (SearchAddOn)

이 검색 엔진에서 사용 설정하는 부가기능입니다.

SearchTier

검색 기능의 등급입니다. 등급에 따라 가격 책정이 달라질 수 있습니다. 자세한 내용은 가격 책정 문서를 참조하세요.

열거형
SEARCH_TIER_UNSPECIFIED 열거형이 지정되지 않은 경우의 기본값입니다. 유효하지 않은 값입니다.
SEARCH_TIER_STANDARD 표준 등급입니다.
SEARCH_TIER_ENTERPRISE 엔터프라이즈 등급입니다.

SearchAddOn

검색에 추가 기능을 제공하는 부가기능입니다.

열거형
SEARCH_ADD_ON_UNSPECIFIED 열거형이 지정되지 않은 경우의 기본값입니다. 유효하지 않은 값입니다.
SEARCH_ADD_ON_LLM 대규모 언어 모델 부가기능입니다.

MediaRecommendationEngineConfig

미디어 추천 엔진을 위한 추가 구성 사양입니다.

JSON 표현 
{
  "type": string,
  "optimizationObjective": string,
  "optimizationObjectiveConfig": {
    object (OptimizationObjectiveConfig)
  },
  "trainingState": enum (TrainingState),
  "engineFeaturesConfig": {
    object (EngineFeaturesConfig)
  }
}
필드
type

string

필수 항목. 엔진 유형입니다. 예: recommended-for-you.

이 필드는 optimizationObjective와 함께 엔진 학습 및 서빙을 제어하는 데 사용하는 엔진 메타데이터를 정의합니다.

현재 지원되는 값: recommended-for-you, others-you-may-like, more-like-this, most-popular-items
optimizationObjective

string

최적화 목표입니다. 예: cvr.

이 필드는 optimizationObjective와 함께 엔진 학습 및 서빙을 제어하는 데 사용하는 엔진 메타데이터를 정의합니다.

현재 지원되는 값: ctr, cvr

지정하지 않으면 엔진 유형에 따라 기본값을 선택합니다. 기본값은 추천 유형에 따라 달라집니다.

recommended-for-you => ctr

others-you-may-like => ctr
optimizationObjectiveConfig

object (OptimizationObjectiveConfig)

cvr 최적화 목표를 위한 커스텀 기준점의 이름과 값입니다. targetField가 watch-time인 경우 target_field_value는 [0, 86400] 범위(0은 제외, 86400은 포함)의 미디어 진행 시간을 나타내는 정수(초 단위)여야 합니다(예: 90). targetField가 watch-percentage인 경우 target_field_value는 (0, 1.0] 범위(0은 제외, 1.0은 포함)의 유효한 부동 소수점 값이어야 합니다(예: 0.5).
trainingState

enum (TrainingState)

엔진의 현재 학습 상태입니다(예: TRAINING 또는 PAUSED).

서비스 실행 비용의 일부는 학습 빈도에 의해 결정되므로, 이 필드를 통해 엔진 학습 시점을 조절하여 비용을 관리할 수 있습니다. 지정하지 않은 경우: engines.create 메서드에서는 기본값이 TRAINING입니다. engines.patch 메서드에서는 기존과 동일한 상태를 유지하는 것이 기본값입니다.
engineFeaturesConfig

object (EngineFeaturesConfig)

선택사항. 엔진 기능에 대한 추가 구성입니다.

OptimizationObjectiveConfig

cvr 최적화 목표를 위한 커스텀 기준점입니다.

JSON 표현 
{
  "targetField": string,
  "targetFieldValueFloat": number
}
필드
targetField

string

필수 항목. 최적화할 대상 필드의 이름입니다. 현재 지원되는 값: watch-percentage, watch-time
targetFieldValueFloat

number

필수 항목. 대상 필드에 적용할 기준점입니다(예: 0.5).

TrainingState

엔진의 학습 상태입니다.

열거형
TRAINING_STATE_UNSPECIFIED 지정되지 않은 학습 상태입니다.
PAUSED 엔진 학습이 일시 중지된 상태입니다.
TRAINING 엔진이 학습 중입니다.

EngineFeaturesConfig

선택한 엔진 유형에 대한 추가 기능 구성입니다.

JSON 표현 
{

  // Union field type_dedicated_config can be only one of the following:
  "recommendedForYouConfig": {
    object (RecommendedForYouFeatureConfig)
  },
  "mostPopularConfig": {
    object (MostPopularFeatureConfig)
  }
  // End of list of possible types for union field type_dedicated_config.
}
필드
통합 필드 type_dedicated_config. 특정 미디어 추천 엔진 유형에 적용되는 기능 관련 구성입니다. type_dedicated_config는 다음 중 하나여야 합니다.
recommendedForYouConfig

object (RecommendedForYouFeatureConfig)

추천 서비스 엔진 기능 구성입니다.

RecommendedForYouFeatureConfig

recommended-for-you 엔진을 만들기 위한 추가 기능 구성입니다.

JSON 표현 
{
  "contextEventType": string
}
필드
contextEventType

string

예측 시 엔진을 쿼리할 때 사용되는 이벤트 유형입니다. 값을 generic으로 설정하면 엔진 학습 시 view-item, media-play, media-complete만 context-event로 사용됩니다. 값을 view-home-page로 설정하면 view-item, media-play, media-complete 외에 view-home-page 이벤트도 context-events로 사용됩니다. 현재 recommended-for-you 엔진에서만 지원됩니다. 현재 지원되는 값: view-home-page, generic

MostPopularFeatureConfig

최고 인기 엔진을 만드는 데 필요한 기능 구성입니다.

JSON 표현 
{
  "timeWindowDays": string
}
필드
timeWindowDays

string (int64 format)

학습 및 예측 시 엔진을 쿼리하는 기간입니다. 양의 정수만 허용됩니다. 이 값은 지난 X일 동안의 이벤트를 의미합니다. 현재 most-popular-items 엔진에서는 필수 값입니다.

ChatEngineMetadata

채팅 엔진에 대한 추가 정보입니다. 이 메시지의 필드는 출력 전용입니다.

JSON 표현 
{
  "dialogflowAgent": string
}
필드
dialogflowAgent

string

이 채팅 엔진이 참조하는 Dialogflow 에이전트의 리소스 이름입니다.

형식: projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>.

CommonConfig

엔진에 대한 공통 구성입니다.

JSON 표현 
{
  "companyName": string
}
필드
companyName

string

엔진과 연관된 회사, 비즈니스 또는 조직의 이름입니다. 이 값을 설정하면 LLM 관련 기능이 향상될 수 있습니다.

AppType

엔진의 앱 유형입니다.

열거형
APP_TYPE_UNSPECIFIED 지정되지 않은 모든 앱 유형입니다.
APP_TYPE_INTRANET 인트라넷 검색 및 Agentspace용 앱 유형입니다.

FeatureState

엔진 기능의 상태입니다.

열거형
FEATURE_STATE_UNSPECIFIED 기능 상태가 지정되지 않았습니다.
FEATURE_STATE_ON 기능이 사용 설정되어 사용할 수 있습니다.
FEATURE_STATE_OFF 기능이 사용 중지되어 사용할 수 없습니다.

ConfigurableBillingApproach

구성 가능한 결제 방식에 대한 설정입니다.

열거형
CONFIGURABLE_BILLING_APPROACH_UNSPECIFIED 기본값입니다. Spark 및 비Spark 환경에서 결제 방식을 구성할 수 없는 경우에 사용되는 일반 가격 책정 모델입니다.
CONFIGURABLE_BILLING_APPROACH_ENABLED 고객이 지정한 구성에 따라 결제 방식이 적용됩니다.

ModelState

엔진에서 모델의 상태를 나타냅니다.

열거형
MODEL_STATE_UNSPECIFIED 모델 상태가 지정되지 않았습니다.
MODEL_ENABLED 관리자가 모델을 사용 설정했습니다.
MODEL_DISABLED 관리자가 모델을 사용 중지했습니다.

메서드

create

 Engine을 만듭니다.

delete

 Engine을 삭제합니다.

get

 Engine을 가져옵니다.

list

 프로젝트와 연결된 모든 Engine을 나열합니다.

patch

 Engine을 업데이트합니다.

pause

 기존 엔진의 학습을 일시중지합니다.

resume

 기존 엔진의 학습을 재개합니다.

tune

 기존 엔진을 조정합니다.