fix(vertexai): route labels to request envelope instead of GenerationConfig (#1865)

Closes #1118

`ChatVertexAI` hard-fails with `ValueError: Unknown field for
GenerationConfig: labels` whenever `labels` is passed at call time
(`.invoke(..., labels={...})` or `.bind(labels=...)`). `"labels"` was
listed in `_allowed_params`, which filters the kwargs used to build the
Gemini `GenerationConfig` — but `GenerationConfig` has no `labels` field
(it belongs on the `GenerateContentRequest` envelope).

A constructor-level `labels=` worked because `self.labels` was passed
straight to `GenerateContentRequest`; only the per-call path leaked into
`GenerationConfig`.

## What

- Remove `"labels"` from `_allowed_params` so it can never reach
`GenerationConfig`.
- In `_prepare_request_gemini`, pop a call-time `labels` kwarg and route
it (falling back to `self.labels`) onto `GenerateContentRequest` across
all return branches. This also fixes the cached-content branches, which
previously dropped labels entirely.
- Add a unit test covering init / per-call-override / per-call-only /
none.
- Drop the now-passing `xfail` markers on the two labels integration
tests.

Author: mdrxy

libs/vertexai/langchain_google_vertexai/chat_models.py

@@ -167,7 +167,6 @@
     "seed",
     "response_logprobs",
     "logprobs",
-    "labels",
     "audio_timestamp",
     "response_modalities",
     "thinking_budget",
@@ -180,7 +179,6 @@
     "request",
     "timeout",
     "metadata",
-    "labels",
     # Allow controlling GAPIC client retries from callers.
     "retry",
 ]
@@ -1899,7 +1897,7 @@ class Joke(BaseModel):
     """
 
     labels: dict[str, str] | None = None
-    """Optional tag llm calls with metadata to help in tracebility and biling."""
+    """Optional tag llm calls with metadata to help in traceability and billing."""
 
     perform_literal_eval_on_string_raw_content: bool = False
     """Whether to perform literal eval on string raw content."""
@@ -2242,6 +2240,14 @@ def _prepare_request_gemini(
         formatted_safety_settings = self._safety_settings_gemini(safety_settings)
         logprobs = logprobs if logprobs is not None else self.logprobs
         logprobs = logprobs if isinstance(logprobs, (int, bool)) else False
+        # `labels` belongs on the request envelope (`GenerateContentRequest`), not on
+        # `GenerationConfig` (which rejects unknown fields) nor on the GAPIC
+        # `generate_content` call (which has no `labels` parameter). It is therefore
+        # excluded from both `_allowed_params` and `_allowed_params_prediction_service`
+        # so it cannot leak into either path. Pop any per-call value here and route it
+        # to the envelope below, falling back to the instance value.
+        request_labels = kwargs.pop("labels", None)
+        request_labels = request_labels if request_labels is not None else self.labels
         generation_config = self._generation_config_gemini(
             stream=stream, stop=stop, logprobs=logprobs, **kwargs
         )
@@ -2334,6 +2340,7 @@ def _content_to_v1(contents: list[Content]) -> list[v1Content]:
                     safety_settings=v1_safety_settings,
                     generation_config=generation_config,
                     cached_content=full_cache_name,
+                    labels=request_labels,
                 )
 
             return GenerateContentRequest(
@@ -2342,6 +2349,7 @@ def _content_to_v1(contents: list[Content]) -> list[v1Content]:
                 safety_settings=formatted_safety_settings,
                 generation_config=generation_config,
                 cached_content=full_cache_name,
+                labels=request_labels,
             )
 
         if self.endpoint_version == "v1":
@@ -2353,7 +2361,7 @@ def _content_to_v1(contents: list[Content]) -> list[v1Content]:
                 safety_settings=v1_safety_settings,
                 generation_config=generation_config,
                 model=self.full_model_name,
-                labels=self.labels,
+                labels=request_labels,
             )
 
         return GenerateContentRequest(
@@ -2364,7 +2372,7 @@ def _content_to_v1(contents: list[Content]) -> list[v1Content]:
             safety_settings=formatted_safety_settings,
             generation_config=generation_config,
             model=self.full_model_name,
-            labels=self.labels,
+            labels=request_labels,
         )
 
     def _request_from_cached_content(

libs/vertexai/tests/integration_tests/test_chat_models.py

@@ -1414,7 +1414,6 @@ async def test_astream_events_langgraph_example() -> None:
     assert output.additional_kwargs["function_call"]["name"] == "multiply"
 
 
-@pytest.mark.xfail(reason="can't add labels to the gemini content")
 @pytest.mark.release
 def test_label_metadata() -> None:
     llm = ChatVertexAI(
@@ -1427,7 +1426,6 @@ def test_label_metadata() -> None:
     llm.invoke("hey! how are you")
 
 
-@pytest.mark.xfail(reason="can't add labels to the gemini content using invoke method")
 @pytest.mark.release
 def test_label_metadata_invoke_method() -> None:
     llm = ChatVertexAI(model=_DEFAULT_MODEL_NAME)

libs/vertexai/tests/unit_tests/test_chat_models.py

@@ -1932,6 +1932,101 @@ def test_thinking_configuration() -> None:
     assert request.generation_config.thinking_config.include_thoughts is True
 
 
+def test_labels_on_request_envelope() -> None:
+    """`labels` belongs on the request envelope, not on `GenerationConfig`.
+
+    Regression test: passing `labels` as an invocation-time keyword used to leak into
+    `GenerationConfig`, which rejects unknown fields and raised
+    ``ValueError: Unknown field for GenerationConfig: labels``.
+    """
+    input_message = HumanMessage("Query.")
+
+    # Init param: labels land on the request envelope.
+    llm = ChatVertexAI(
+        model=_DEFAULT_MODEL_NAME,
+        project="test-project",
+        labels={"team": "qa"},
+    )
+    request = llm._prepare_request_gemini([input_message])
+    assert dict(request.labels) == {"team": "qa"}
+
+    # Invocation param must not raise (the regression) and overrides the init value.
+    request = llm._prepare_request_gemini([input_message], labels={"env": "prod"})
+    assert dict(request.labels) == {"env": "prod"}
+
+    # Invocation param with no init value.
+    llm = ChatVertexAI(model=_DEFAULT_MODEL_NAME, project="test-project")
+    request = llm._prepare_request_gemini([input_message], labels={"only": "per-call"})
+    assert dict(request.labels) == {"only": "per-call"}
+
+    # No labels anywhere.
+    request = llm._prepare_request_gemini([input_message])
+    assert dict(request.labels) == {}
+
+
+def test_labels_on_request_envelope_cached_content() -> None:
+    """`labels` reach the envelope on the cached-content path.
+
+    Previously the cached-content branches omitted `labels` entirely, silently
+    dropping them; init-time and per-call values must now propagate.
+    """
+    input_message = HumanMessage("Query.")
+
+    llm = ChatVertexAI(
+        model=_DEFAULT_MODEL_NAME,
+        project="test-project",
+        cached_content="my-cache",
+        labels={"team": "qa"},
+    )
+    request = llm._prepare_request_gemini([input_message])
+    assert dict(request.labels) == {"team": "qa"}
+
+    request = llm._prepare_request_gemini([input_message], labels={"env": "prod"})
+    assert dict(request.labels) == {"env": "prod"}
+
+
+def test_labels_on_request_envelope_v1_endpoint() -> None:
+    """`labels` reach the envelope on the ``v1`` endpoint path."""
+    input_message = HumanMessage("Query.")
+
+    llm = ChatVertexAI(
+        model=_DEFAULT_MODEL_NAME,
+        project="test-project",
+        endpoint_version="v1",
+        labels={"team": "qa"},
+    )
+    request = llm._prepare_request_gemini([input_message])
+    assert dict(request.labels) == {"team": "qa"}
+
+    request = llm._prepare_request_gemini([input_message], labels={"env": "prod"})
+    assert dict(request.labels) == {"env": "prod"}
+
+
+def test_labels_via_public_invoke() -> None:
+    """End-to-end: ``invoke(..., labels=...)`` routes labels to the envelope only.
+
+    Guards the user-facing path. ``labels`` must land on ``request.labels`` and must
+    NOT leak as a keyword to the GAPIC ``generate_content`` call, which has no
+    ``labels`` parameter and would raise ``TypeError`` in production.
+    """
+    with patch(
+        "langchain_google_vertexai._client_utils.v1beta1PredictionServiceClient"
+    ) as mc:
+        response = GenerateContentResponse(
+            candidates=[Candidate(content=Content(parts=[Part(text="Hi")]))]
+        )
+        mock_generate_content = MagicMock(return_value=response)
+        mc.return_value.generate_content = mock_generate_content
+
+        llm = ChatVertexAI(model=_DEFAULT_MODEL_NAME, project="test-project")
+        llm.invoke([HumanMessage("Query.")], labels={"env": "prod"})
+
+        mock_generate_content.assert_called_once()
+        call_kwargs = mock_generate_content.call_args.kwargs
+        assert dict(call_kwargs["request"].labels) == {"env": "prod"}
+        assert "labels" not in call_kwargs
+
+
 def test_thought_signature() -> None:
     """Test that thought signatures are correctly parsed and included in requests."""
     llm = ChatVertexAI(