Skip to content

feat(vertexairagtool): expose RAG retrieval configuration - #2324

Open
dhakad22klx wants to merge 10 commits into
google:mainfrom
dhakad22klx:feat/vertexairagtool-expose-rag-retrieval-config
Open

dhakad22klx wants to merge 10 commits into
google:mainfrom
dhakad22klx:feat/vertexairagtool-expose-rag-retrieval-config

Conversation

@dhakad22klx

@dhakad22klx dhakad22klx commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Closes: #2289

Problem:

vertexairagtool.Config does not expose RAGRetrievalConfig, preventing callers from configuring hybrid search, ranking/reranking, filters, and context count.

Solution:

Add optional RAGRetrievalConfig *genai.RAGRetrievalConfig, pass it through to VertexRAGStore, and deep-copy all nested pointers during construction and request processing to preserve mutation isolation.

Behavior change

Callers can configure the additional retrieval options. Existing callers that omit the field retain their current behavior.

Testing Plan

Unit Tests:

  • Full workspace race suite passed: go test -race -mod=readonly -count=1 -shuffle=on ./....
  • Build, lint, and tidy checks passed across both modules.
  • Tests cover nil, empty, partial, zero-valued, and populated configurations, plus caller and request mutations.

With your source change reverted and your tests kept, which test fails?

Removing pass-through makes TestProcessRequest_RAGRetrievalConfig fail. Removing nested copies makes TestNew_CopiesConfig and TestProcessRequest_CopiesStorePerRequest fail.

Manual End-to-End (E2E) Tests:

Tested against a live Vertex AI RAG corpus containing my resume (pdf file).

Setup, replacing placeholders with the project and corpus used for testing:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_CORPUS_REGION"
export GOOGLE_MODEL="gemini-3.5-flash"
export RAG_CORPUS="projects/${GOOGLE_CLOUD_PROJECT}/locations/YOUR_CORPUS_REGION/ragCorpora/YOUR_CORPUS_ID"

gcloud auth login
gcloud config set project "$GOOGLE_CLOUD_PROJECT"
gcloud services enable aiplatform.googleapis.com
gcloud auth application-default login

go run ./examples/tools/vertexairagtool console

Repeated the following prompt with each retrieval configuration:

what are the projects in my resume ?

Configuration Result
RAGRetrievalConfig omitted Passed. Returned project and work-experience information from the resume.
TopK: 1 Passed. Identified JustSay, the resume’s single project.
TopK: 3, HybridSearch.Alpha: 0.1 Passed. Identified JustSay with the correct description and technologies.

These runs verify live request acceptance and corpus-grounded responses.

Checklist

  • Performed self-review of changes i made.
  • Added regression tests and verified they detect removed functionality.
  • New and existing tests pass locally.

@dhakad22klx
dhakad22klx force-pushed the feat/vertexairagtool-expose-rag-retrieval-config branch from 27e0d7b to 5338a49 Compare November 14, 2026 05:19
@wojtas000 wojtas000 self-assigned this Nov 15, 2026

@wojtas000 wojtas000 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs one fix before merge: users can now set top-k and the vector distance threshold in two places each, and nothing says which value the backend uses. The PR's own expected request sends both with different values (top-k 3 and 5, threshold 0.5 and 0.4).

Before this PR, SimilarityTopK and VectorDistanceThreshold were the only way to cap or filter results. Now RAGRetrievalConfig.TopK and RAGRetrievalConfig.Filter.VectorDistanceThreshold set the same things. New accepts both members of each pair and sends both, and every one of these fields is still documented as the knob that controls results. Please choose one rule, test it, and document it on all three fields. Either New returns an error when both members of a pair are set, or you mark SimilarityTopK and VectorDistanceThreshold as superseded and say that RAGRetrievalConfig wins. Then change wantStore() so the copy tests stop treating a conflicting config as the normal case.

On adk-python parity: VertexAiRagRetrieval.__init__ in adk-python (src/google/adk/tools/retrieval/vertex_ai_rag_retrieval.py) takes only rag_corpora, rag_resources, similarity_top_k and vector_distance_threshold, so this option exists only in Go. The package is experimental and the field passes a genai type straight through, so I don't see that as a reason to reject the PR. The empty description should still say why the option belongs here and not in geminitool.New, which can already send any VertexRAGStore, and link a matching adk-python issue if there is one.

The deep copy is complete for every field the tests use, and the copy tests would catch a missing clone. A nil RAGRetrievalConfig leaves requests exactly as they were.

Three adk-python tests in tools/retrieval/test_vertex_ai_rag_retrieval.py fail on main and still fail with this PR: test_vertex_rag_retrieval_for_gemini_2_x, test_vertex_rag_retrieval_for_non_gemini and test_vertex_rag_retrieval_for_non_gemini_with_another_function_tool. They check the store shape adk-python sends to Gemini and its function-declaration fallback for non-Gemini models, which this package doesn't offer. They don't involve retrieval config, so this PR doesn't need to change anything for them. workflow/test_llm_agent_as_node.py::test_parallel_single_turn_nodes_only_see_own_node_input is flaky on main too and doesn't touch this package.

// RAGRetrievalConfig configures filtering, hybrid search, ranking and context
// count. Nil leaves the backend defaults in place. These options extend the
// configuration supported by the Python retrieval tool.
RAGRetrievalConfig *genai.RAGRetrievalConfig

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: this field overlaps SimilarityTopK (via TopK) and VectorDistanceThreshold (via Filter.VectorDistanceThreshold). New sends both, and no doc says which value applies. Please either reject a config that sets both members of a pair, or document that this field takes precedence and mark the old two as superseded, and add a test for whichever rule you pick.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushed required fixes in latest commit 72a56a0.

Comment thread exp/vertexairagtool/vertexairag.go Outdated

// RAGRetrievalConfig configures filtering, hybrid search, ranking and context
// count. Nil leaves the backend defaults in place. These options extend the
// configuration supported by the Python retrieval tool.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: please drop the sentence about the Python retrieval tool. It goes stale when adk-python changes. Say instead what the field sends and how it relates to SimilarityTopK and VectorDistanceThreshold.

@dhakad22klx dhakad22klx Nov 16, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushed fixes in latest commit.

}
}

func retrievalConfig() *genai.RAGRetrievalConfig {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this fixture sets both vector thresholds and both rankers. The Vertex API accepts only one of each pair, so it describes a request the backend would reject. Use one threshold and one ranker here, and cover the other member of each pair in its own case. Also stop setting conflicting SimilarityTopK/VectorDistanceThreshold values in wantStore().

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pushed fixes in latest commit.

Comment thread examples/tools/vertexairagtool/main.go Outdated
HybridSearch: &genai.RAGRetrievalConfigHybridSearch{
Alpha: new(float32(0.1)),
},
// Filter configures metadata/vector thresholds; Ranking configures reranking.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this comment describes fields the example doesn't set. Remove it or show a real Filter/Ranking line. Also note that the example now turns on hybrid search for any corpus the user points it at.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped this extra comment in latest commit 0daf029 .

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(vertexairagtool): support RAGRetrievalConfig

2 participants