docs(vector_stores): separate managed Vertex AI Search from pass-through

[oss-agent-shin]

Linear: LIT-3229

Why

A customer asked us to "add Vertex AI Search support on the API." That
capability already exists today — POST /vector_store/new writes a row
to LiteLLM_ManagedVectorStoresTable for custom_llm_provider: vertex_ai/search_api, which is what the Admin UI uses and what the
unified /v1/vector_stores/{id}/search endpoint resolves against
(litellm/proxy/vector_store_endpoints/management_endpoints.py:515,
litellm/llms/vertex_ai/vector_stores/search_api/transformation.py).

The customer couldn't find it because our docs steered them wrong on
three counts:

1. docs/pass_through/vertex_ai_search_datastores.md was filed under
   pass-through but actually mostly documented a managed vector
   store (the vector_store_registry YAML stanza), which conflated
   the two surfaces in one page.
2. docs/vector_stores/create.md only listed OpenAI / Azure / RAGFlow
   for POST /v1/vector_stores and never mentioned that Vertex AI
   Search registration uses a different endpoint
   (POST /vector_store/new).
3. The example YAML on the pass-through page included
   vertex_app_id, which the code does not read — grep -rn vertex_app_id litellm/ tests/ returns 0 hits. A customer who
   pasted that snippet into their config got it silently ignored.

What's in this PR

1. New file docs/providers/vertex_ai_search_vector_stores.md —
   single managed-mode walkthrough that covers prerequisites,
   registration via config.yaml vector_store_registry, via
   POST /vector_store/new, and via the Admin UI; then query via
   POST /v1/vector_stores/{id}/search and litellm.vector_stores.search().
   Includes a "when to use this vs the pass-through" table that
   redirects the other half of users.

2. Trimmed docs/pass_through/vertex_ai_search_datastores.md so
   it covers only the pass-through endpoint
   (/vertex_ai/discovery/...). Removed the managed
   vector_store_registry YAML stanza (now lives on the providers
   page) and all vertex_app_id references (no-op today). Added
   a tip at the top of the page pointing users who want the unified
   API at the new providers page.

3. Updated docs/vector_stores/create.md with a callout
   distinguishing:

   • POST /v1/vector_stores — creates an upstream store on the
     provider (OpenAI / Azure / RAGFlow).
   • POST /vector_store/new — registers an existing upstream store
     as a LiteLLM-managed mapping (Vertex AI Search, Azure AI Search,
     Milvus, Gemini File Search, Bedrock KB).

   Also added a new tab in the curl examples that shows the
   POST /vector_store/new payload using the Vertex AI Search shape.

4. Wired the new page into sidebars.js under the existing
   Vertex AI provider category.

Acceptance checklist (from the ticket)

• Customer can land on the Vertex AI Search docs page and find
  both API-based and UI-based registration without reading code.
• Pass-through page no longer references the managed registry.
• create.md answers "which endpoint do I use for X provider"
  without ambiguity.
• No vertex_app_id in any YAML/JSON example anywhere in the
  docs.

Manual testing evidence

1. vertex_app_id really is a no-op (so it's safe to remove)

$ cd litellm && grep -rn "vertex_app_id" litellm/ tests/
$  # 0 hits

The field was never read anywhere in source or tests, so pasting it
into a config silently does nothing — confirming the ticket
diagnosis.

2. The new docs' code path actually works (mocked end-to-end)

The existing test tests/vector_store_tests/test_vertex_ai_search_api_vector_store.py
exercises exactly the SDK call this PR documents:

$ python -m pytest tests/vector_store_tests/test_vertex_ai_search_api_vector_store.py -v
tests/vector_store_tests/test_vertex_ai_search_api_vector_store.py::TestVertexAISearchAPIVectorStore::test_basic_search_sync_with_mock PASSED [ 50%]
tests/vector_store_tests/test_vertex_ai_search_api_vector_store.py::TestVertexAISearchAPIVectorStore::test_basic_search_with_mock PASSED [100%]
============================== 2 passed in 0.68s ===============================

I also ran the exact Python SDK example from the new
vertex_ai_search_vector_stores.md against a mocked Discovery Engine
response to confirm the URL we route to and the response shape both
match what the docs claim:

# Same as the "Python SDK" tab in the new docs page
response = litellm.vector_stores.search(
    vector_store_id="my-datastore_1234567890",
    query="How do I authenticate?",
    custom_llm_provider="vertex_ai/search_api",
    vertex_project="my-gcp-project",
    vertex_location="global",
)

Captured:

URL the docs example hits:
  https://discoveryengine.googleapis.com/v1/projects/my-gcp-project/locations/global/collections/default_collection/dataStores/my-datastore_1234567890/servingConfigs/default_config:search

Response (normalized to LiteLLM/OpenAI shape):
{
  "object": "vector_store.search_results.page",
  "search_query": "How do I authenticate?",
  "data_len": 1,
  "first_result_keys": ["attributes", "content", "file_id", "filename", "score"],
  "attributes": {
    "document_id": "0",
    "link": "https://docs.litellm.ai/docs/",
    "title": "LiteLLM Docs"
  }
}

That matches the "Response Format" section of the new docs page
exactly (object name, top-level keys, per-result keys, and the
document_id / link / title attributes).

3. POST /vector_store/new endpoint really lives where the docs say

$ sed -n '514,520p' litellm/proxy/vector_store_endpoints/management_endpoints.py
@router.post(
    "/vector_store/new",
    tags=["vector store management"],
    dependencies=[Depends(user_api_key_auth)],
)
async def new_vector_store(
    vector_store: LiteLLM_ManagedVectorStore,

Confirms the curl snippets in vertex_ai_search_vector_stores.md and
the new tab in create.md hit the actual route.

Files changed (4)

File	Status	+/-
docs/providers/vertex_ai_search_vector_stores.md	added	+264
docs/pass_through/vertex_ai_search_datastores.md	modified	+25 / -31
docs/vector_stores/create.md	modified	+45 / -0
sidebars.js	modified	+1 / -0

Agent session: https://litellm-agent-platform.onrender.com/sessions/5a30f91b-4eaa-4c05-9bea-2d8d7968f19d

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	May 25, 2026 6:51pm

[mubashir1osmani]

@oss-agent-shin is there a PR on the litellm repo for this?

[mubashir1osmani]

some info is misleading, will merge into my branch and fix