Merge pull request #16523 from BerriAI/litellm_add_openai_metadata_field

Enable OpenAI metadata passthrough in the request

Author: Sameerlite

docs/my-website/docs/providers/openai.md

@@ -29,6 +29,18 @@ response = completion(
 )
 ```
 
+:::info Metadata passthrough (preview)
+When `litellm.enable_preview_features = True`, LiteLLM forwards only the values inside `metadata` to OpenAI.
+
+```python
+completion(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "hi"}],
+    metadata= {"custom_meta_key": "value"},
+)
+```
+:::
+
 ### Usage - LiteLLM Proxy Server
 
 Here's how to call OpenAI models with the LiteLLM Proxy Server

litellm/main.py

@@ -105,7 +105,7 @@
     ProviderConfigManager,
     Usage,
     _get_model_info_helper,
-    add_openai_metadata,
+    get_requester_metadata,
     add_provider_specific_params_to_optional_params,
     async_mock_completion_streaming_obj,
     convert_to_model_response_object,
@@ -2086,10 +2086,12 @@ def completion(  # type: ignore # noqa: PLR0915
             if extra_headers is not None:
                 optional_params["extra_headers"] = extra_headers
 
-            if litellm.enable_preview_features:
-                metadata_payload = add_openai_metadata(metadata)
-                if metadata_payload is not None:
-                    optional_params["metadata"] = metadata_payload
+            if (
+                litellm.enable_preview_features and metadata is not None
+            ):  # [PREVIEW] allow metadata to be passed to OPENAI
+                openai_metadata = get_requester_metadata(metadata)
+                if openai_metadata is not None:
+                    optional_params["metadata"] = openai_metadata
 
             ## LOAD CONFIG - if set
             config = litellm.OpenAIConfig.get_config()

litellm/utils.py

@@ -8088,6 +8088,21 @@ def add_openai_metadata(metadata: Optional[Mapping[str, Any]]) -> Optional[Dict[
 
     return visible_metadata.copy()
 
+def get_requester_metadata(metadata: dict):
+    if not metadata:
+        return None
+
+    requester_metadata = metadata.get("requester_metadata")
+    if isinstance(requester_metadata, dict):
+        cleaned_metadata = add_openai_metadata(requester_metadata)
+        if cleaned_metadata:
+            return cleaned_metadata
+
+    cleaned_metadata = add_openai_metadata(metadata)
+    if cleaned_metadata:
+        return cleaned_metadata
+
+    return None
 
 def return_raw_request(endpoint: CallTypes, kwargs: dict) -> RawRequestTypedDict:
     """

tests/llm_translation/test_optional_params.py

@@ -23,6 +23,7 @@
     get_optional_params,
     get_optional_params_embeddings,
     get_optional_params_image_gen,
+    get_requester_metadata,
 )
 
 ## get_optional_params_embeddings
@@ -67,6 +68,41 @@ def test_anthropic_optional_params(stop_sequence, expected_count):
     assert len(optional_params) == expected_count
 
 
+def test_get_requester_metadata_returns_none_for_empty():
+    metadata = {"requester_metadata": {}}
+    assert get_requester_metadata(metadata) is None
+
+
+@patch("litellm.main.openai_chat_completions.completion")
+def test_requester_metadata_forwarded_to_openai(mock_completion):
+    mock_completion.return_value = MagicMock()
+    metadata = {
+        "requester_metadata": {
+            "custom_meta_key": "value",
+            "hidden_params": "secret",
+            "int_value": 123,
+        }
+    }
+
+    original_api_key = litellm.api_key
+    litellm.api_key = "sk-test"
+    original_preview_flag = litellm.enable_preview_features
+    litellm.enable_preview_features = True
+
+    try:
+        litellm.completion(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "hi"}],
+            metadata=metadata,
+        )
+    finally:
+        litellm.api_key = original_api_key
+        litellm.enable_preview_features = original_preview_flag
+
+    sent_metadata = mock_completion.call_args.kwargs["optional_params"]["metadata"]
+    assert sent_metadata == {"custom_meta_key": "value"}
+
+
 def test_get_optional_params_with_allowed_openai_params():
     """
     Test if use can dynamically pass in allowed_openai_params to override default behavior