fix(vector-stores): support engines URL for Vertex AI Search

[ryan-crabbe-berri]

Summary

Adds an optional vertex_engine_id field to the vertex_ai/search_api provider so a managed vector store can point at a Discovery Engine search app (engine) instead of a single data store. When set, get_complete_url routes to the engines/{id}/servingConfigs/default_serving_config URL; when absent, behavior is unchanged (dataStores/{id}/servingConfigs/default_config). This lets one store fan out across an app's data stores and reuse the same data store across multiple apps without re-registering it.

Screenshots

Test plan

• tests/test_litellm/llms/vertex_ai/test_vertex_ai_search_vector_store_transformation.py — engines URL branch, precedence over vector_store_id, URL-encoding, dot-segment rejection, and "neither provided" error; existing dataStores cases kept as regression guards.
• E2E against real GCP across multiple app/data-store topologies (verifying both the outbound …/engines/{id}/…:search URL and response provenance):
  • App with 1 data store
  • App with 2 data stores
  • Two apps that share the same data store (confirm each app's config is applied, no re-registration needed)
  • Data-store-direct store (no engine ID) — regression, still uses dataStores URL

Resolves LIT-3036

[greptile-apps]

Greptile Summary

This PR fixes GCP 400 FAILED_PRECONDITION errors for website, healthcare, and connector-based Vertex AI data stores by adding an optional vertex_engine_id parameter that routes search through the Discovery Engine engines URL (/engines/{id}/servingConfigs/default_serving_config) instead of the direct dataStores URL. Existing callers without an engine ID are unaffected.

• Backend (transformation.py): get_complete_url branches on vertex_engine_id in litellm_params; the api_base guard is also moved to the top, fixing a pre-existing issue where supplying api_base without vector_store_id would incorrectly raise a ValueError.
• Tests: Five new unit tests cover URL construction, path-traversal encoding, dot-segment rejection, engine-over-datastore precedence, and the missing-both-IDs error path — all without network calls.
• UI: Adds the optional Engine ID field to the vertex_ai/search_api provider config and updates the help Alert with two-case guidance (data-store ID vs. Engine ID), with the vector_store_id placeholder updating dynamically when an engine ID is entered.

Confidence Score: 5/5

Safe to merge — additive change with no impact on existing data-store-direct callers, backed by good unit-test coverage and manual E2E validation.

The change is strictly additive: the new engines URL branch only activates when vertex_engine_id is explicitly set, and the api_base short-circuit fix is a correctness improvement rather than a regression risk. URL encoding reuses the existing encode_url_path_segment helper with the same dot-segment and path-traversal protections. Tests cover all new and existing code paths without real network calls.

No files require special attention beyond noting that vertex_engine_id is not yet a declared field in CredentialLiteLLMParams.

Important Files Changed

Filename	Overview
litellm/llms/vertex_ai/vector_stores/search_api/transformation.py	Adds engines URL branch to get_complete_url; moves api_base guard to the top; encodes engine_id with the existing encode_url_path_segment helper. Logic is clean and safe.
tests/test_litellm/llms/vertex_ai/test_vertex_ai_search_vector_store_transformation.py	Five new unit tests cover the engines URL path: happy path, engine-over-datastore precedence, path-traversal encoding, dot-segment rejection, and the error case when neither ID is set. No real network calls made.
ui/litellm-dashboard/src/components/vector_store_providers.tsx	Adds optional vertex_engine_id field to the vertex_ai/search_api provider config definition. Straightforward additive change.
ui/litellm-dashboard/src/components/vector_store_management/VectorStoreForm.tsx	Watches vertex_engine_id via Form.useWatch to update the vector_store_id placeholder dynamically; expands the help Alert with two-case guidance. UI behavior is correct.

_{Reviews (2): Last reviewed commit: "fix(vector-stores): support engines URL ..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...rtex_ai/vector_stores/search_api/transformation.py	91.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Sameerlite]

LGTM, thanks. Please make sure CICD is all green before merging

[ryan-crabbe-berri]

followup to this, it seems the original implementation we have actually works on googles side if you configure an engine that has that data store in it, so maybe the better solution is to support engines in a more direct way instead of like this

going to update docs in the meantime

[ryan-crabbe-berri]

yea gonne clsoe we should support engines/vertex apps in a different more explicit way if we do, this would be misleading @Sameerlite

[ryan-crabbe-berri]

this works, will need a follow up that allows for per request overrides for things like dataStoreSpecs[]