# The ModelService object A governed AI Gateway endpoint in Unity Catalog that routes inference requests to one or more model destinations (for example a foundation model or an external LLM reached through a ModelProviderService). Applies centralized access control, rate limits, guardrails, and auditing to the traffic it serves. ## Attributes - `name` (string, Beta) Resource name of the model service. Format: `model-services/{catalog}.{schema}.{model_service}`. Each `{...}` component is capped at 255 characters individually. Server-derived on Create from `parent` + `model_service_id`; required and immutable on Update/Get/Delete. - `owner` (string, Beta) The owner of the model service. Write-only; read owner via effective_owner. - `effective_owner` (string, Beta) The resolved owner of the ModelService. Falls back to the caller's identity when `owner` is not explicitly set on creation. - `metastore_id` (string, Beta) Metastore hosting the model service. - `create_time` (string, Beta) When the model service was created. - `created_by` (string, Beta) Creator identity. - `update_time` (string, Beta) When the model service was last modified. - `updated_by` (string, Beta) Identity of the last updater. - `comment` (string, Beta) User-provided description. Constraints: `<= 65536 characters` - `config` (object, Beta) Operational configuration: destinations, routing, rate limits, inference table. Required on CreateModelService; on UpdateModelService it is required only when `config` (or a `config.*` subpath) appears in `update_mask`. - `routing` (object, Beta) Routing configuration: destinations, routing strategy, and fallback. - `destinations` (array of object, Beta) Primary routing destinations. At most 10 are allowed. At least one is required on CreateModelService; on UpdateModelService it is required only when `config.routing` (or a `config.routing.*` subpath) appears in `update_mask`. - `name` (string, Beta) User-facing label for this destination, used in routing references. - `destination_type` (string, Beta) Backing-model category. Determines which oneof variant is populated. Possible values: `DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL`, `DESTINATION_TYPE_PROVISIONED_THROUGHPUT_FOUNDATION_MODEL`, `DESTINATION_TYPE_EXTERNAL_FOUNDATION_MODEL` - `traffic_percentage` (int32, Beta) Share of traffic sent to this destination, 0-100. Optional on fallback destinations; see FallbackConfig. - `pay_per_token_config` (object, Beta) - `provisioned_throughput_config` (object, Beta) - `external_model_config` (object, Beta) - `is_deleted` (boolean, Beta) True when the destination's backing UC entity (MODEL for foundation-model destinations, MODEL_PROVIDER_SERVICE for external destinations) has been deleted but the destination row still references it. The dangling destination is surfaced (not silently dropped) so callers can see the broken routing. Inference traffic through this destination fails closed (BAD_REQUEST / FAILED_PRECONDITION). - `traffic_splitting` (object, Beta) Marker message selecting request-based traffic splitting. Traffic is distributed according to each destination's traffic_percentage value; no configuration lives on this message itself. - `fallback` (object, Beta) Fallback routing config, applied after primary destinations fail. - `destinations` (array of object, Beta) Ordered list of fallback destinations. Traversal is in list order; the attempt count is the length of the list. At most 5 are allowed. - `first_token_timeout` (string, Beta) Timeout for the first token of a streaming response. If a destination does not return its first token within this duration, AI Gateway aborts the attempt and fails over to the next destination. Applies to streaming requests only. Leave unset for no first-token timeout. - `rate_limits` (array of object, Beta) Rate limits applied to requests routed through this model service. - `key` (string, Beta) Scope key. Determines whether `principal` is required. Possible values: `RATE_LIMIT_KEY_USER`, `RATE_LIMIT_KEY_USER_GROUP`, `RATE_LIMIT_KEY_SERVICE_PRINCIPAL`, `RATE_LIMIT_KEY_SERVICE`, `RATE_LIMIT_KEY_USER_DEFAULT`, `RATE_LIMIT_KEY_REQUEST_TAG` - `renewal_period` (string, Beta) Renewal period. Possible values: `RATE_LIMIT_RENEWAL_PERIOD_MINUTE`, `RATE_LIMIT_RENEWAL_PERIOD_HOUR` - `principal` (string, Beta) Principal this limit applies to: user email, group name, or service principal application ID. Required unless `key` is `RATE_LIMIT_KEY_SERVICE`, `RATE_LIMIT_KEY_USER_DEFAULT`, or `RATE_LIMIT_KEY_REQUEST_TAG` (which must not set a principal). - `requests` (int64, Beta) Max requests allowed within a renewal period. Leave unset for no request limit. - `tokens` (int64, Beta) Max tokens allowed within a renewal period. Leave unset for no token limit. - `request_tag_key` (string, Beta) Request tag key this limit applies to. Required when `key` is `RATE_LIMIT_KEY_REQUEST_TAG`, forbidden otherwise. - `request_tag_value` (string, Beta) Request tag value this limit applies to. Only valid when `key` is `RATE_LIMIT_KEY_REQUEST_TAG`. Leave unset to apply the limit to every value of `request_tag_key` (an any-value default); a set value is a specific override for that value. - `inference_table` (object, Beta) Inference table config for payload logging. - `parent` (string, Beta) Parent UC schema where the inference table is created. Format: `schemas/{catalog}.{schema}`. Set at create time and immutable thereafter; changing it on an existing service is rejected. - `table_name_prefix` (string, Beta) Prefix for the inference-table's UC-registered name. The actual leaf name UC stores is `_payload`; the `_payload` suffix is appended automatically. To find the actual UC table after Create, read the `table` field on the response. Defaults to `_payload` when unset. Set at create time and immutable thereafter; changing it on an existing service is rejected. - `disabled` (boolean, Beta) Indicates whether payload logging is disabled (opt-out). Unset means that payload logging is active (the on-by-default state coincides with the proto zero-value, so the server never fills this field for a client that leaves it unset). Set `disabled = true` to pause runtime logging while keeping the sub-message attached (preserving `parent` and `table_name_prefix` for a later flip back to active). `parent` remains required either way. - `table` (string, Beta) Resolved UC table for payload logs. Format: `tables/{catalog}.{schema}.{table}`. - `is_deleted` (boolean, Beta) True when the bound inference TABLE has been deleted but the parent service still references it. The dangling reference is surfaced (not silently dropped) so callers can see the broken dependency. AI Gateway payload logging fails closed in this state. - `etag` (string, Beta) Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated `etag` field on the Update / Delete request; the server rejects the mutation if the stored etag differs. - `supported_api_types` (array of string, Beta) Unified API types this endpoint supports (e.g. "chat", "embeddings", "completions"). Derived from the destinations' backing models / providers at read time. ## Example ```json { "name": "string", "owner": "string", "effective_owner": "string", "metastore_id": "string", "create_time": "string", "created_by": "string", "update_time": "string", "updated_by": "string", "comment": "string", "config": { "routing": {}, "rate_limits": [ {} ], "inference_table": {} }, "etag": "string", "supported_api_types": [ "string" ] } ```