Deprecate WorkspaceClient().serving_endpoints.get_open_ai_client() and WorkspaceClient().serving_endpoints.get_langchain_chat_open_ai_client() methods (#1238)

# Deprecate get_open_ai_client and get_langchain_chat_open_ai_client
methods
These methods are now deprecated in favor of the databricks-openai and
databricks-langchain package.

Instead of
```
pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()
response = client.chat.completions.create(model="databricks-claude-sonnet-4-5", ...)
```

We now recommend
```
pip install databricks-openai

from databricks_openai import DatabricksOpenAI # or AsyncDatabricksOpenAI
client = DatabricksOpenAI()
response = client.chat.completions.create(model="databricks-claude-sonnet-4-5", ...)                                                                             
```
## What changes are proposed in this pull request?
**WHAT:**
This PR deprecates two OpenAI client helper methods in the Databricks
SDK:
1. `ServingEndpointsExt.get_open_ai_client()`
2. `ServingEndpointsExt.get_langchain_chat_open_ai_client()`
The changes include:
- Adding `DeprecationWarning` messages that are raised when either
method is called, with clear instructions to migrate to the
`databricks-openai` package
- Updating docstrings with `.. deprecated::` directives pointing users
to the new package
- Adding test coverage to verify the deprecation warnings are properly
raised
- The methods remain functional - this is a soft deprecation that warns
users but doesn't break existing code
**WHY:**
These helper methods were originally added to the Databricks SDK to make
it easier to use OpenAI-compatible clients with Databricks Model
Serving. However,
maintaining OpenAI client integration directly in the SDK creates
several issues:
1. **Tight coupling**: The SDK shouldn't be tightly coupled to specific
client libraries (OpenAI, LangChain) which have their own release cycles
and breaking
changes
2. **Feature richness**: A dedicated package (`databricks-openai`) can
provide more comprehensive OpenAI compatibility features without
bloating the core SDK
3. **Maintenance burden**: Separating concerns allows the OpenAI
integration to evolve independently from the core SDK functionality
4. **Better user experience**: The `databricks-openai` package provides
a more standard OpenAI-compatible interface that users familiar with the
OpenAI SDK will
find more intuitive
By deprecating these methods now, we give users a clear migration path
while maintaining backward compatibility. The deprecation warnings will
appear in users'
logs, guiding them to adopt the better-maintained `databricks-openai`
package.
## How is this tested?
**Unit tests:**
- Added `test_get_open_ai_client_deprecation_warning()` which verifies
that calling `get_open_ai_client()` raises a `DeprecationWarning` with
the correct
message pointing to `databricks-openai` and `DatabricksOpenAI`
- Added `test_get_langchain_chat_open_ai_client_deprecation_warning()`
which verifies that calling `get_langchain_chat_open_ai_client()` raises
a
`DeprecationWarning` with the correct message pointing to
`AsyncDatabricksOpenAI`. This test handles both cases where
`langchain_openai` is installed and not
installed.
- Verified all existing tests still pass (with expected deprecation
warnings now appearing in test output)
**Manual verification:**
All new tests pass locally:
pytest
tests/test_open_ai_mixin.py::test_get_open_ai_client_deprecation_warning
-v # PASSED
pytest
tests/test_open_ai_mixin.py::test_get_langchain_chat_open_ai_client_deprecation_warning
-v # PASSED
The deprecation warnings are correctly raised in all existing tests that
use these methods, confirming the warnings will be visible to end users.

---------

Signed-off-by: Siddharth Murching <smurching@gmail.com>
Signed-off-by: Sid Murching <sid.murching@databricks.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: smurching

NEXT_CHANGELOG.md

@@ -17,3 +17,4 @@
 ### Internal Changes
 
 ### API Changes
+* Deprecated `WorkspaceClient.serving_endpoints.get_open_ai_client()` and `WorkspaceClient.serving_endpoints.get_langchain_chat_open_ai_client()` methods in favor of dedicated packages. Users should migrate to `databricks-openai` (using `DatabricksOpenAI`) and `databricks-langchain` (using `ChatDatabricks`) respectively ([#1238](https://github.com/databricks/databricks-sdk-py/pull/1238)).

databricks/sdk/mixins/open_ai_client.py

@@ -1,4 +1,5 @@
 import json as js
+import warnings
 from typing import Dict, Optional
 
 from requests import Response
@@ -34,6 +35,11 @@ def auth_flow(self, request: httpx.Request) -> httpx.Request:
     def get_open_ai_client(self, **kwargs):
         """Create an OpenAI client configured for Databricks Model Serving.
 
+        .. deprecated::
+            This method is deprecated. Please install the `databricks-openai` package
+            and use `from databricks_openai import DatabricksOpenAI` instead.
+            See https://api-docs.databricks.com/python/databricks-ai-bridge/latest/databricks_openai.html for more information.
+
         Returns an OpenAI client instance that is pre-configured to send requests to
         Databricks Model Serving endpoints. The client uses Databricks authentication
         to query endpoints within the workspace associated with the current WorkspaceClient
@@ -66,6 +72,13 @@ def get_open_ai_client(self, **kwargs):
             ...     max_retries=5
             ... )
         """
+        warnings.warn(
+            "get_open_ai_client() is deprecated. Please install the databricks-openai package "
+            "and use 'from databricks_openai import DatabricksOpenAI' instead. "
+            "See https://api-docs.databricks.com/python/databricks-ai-bridge/latest/databricks_openai.html for more information.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         try:
             from openai import OpenAI
         except Exception:
@@ -95,6 +108,20 @@ def get_open_ai_client(self, **kwargs):
         return OpenAI(**client_params)
 
     def get_langchain_chat_open_ai_client(self, model):
+        """Create a LangChain ChatOpenAI client configured for Databricks Model Serving.
+
+        .. deprecated::
+            This method is deprecated. Please install the `databricks-langchain` package
+            and use `from databricks_langchain import ChatDatabricks` instead.
+            See https://api-docs.databricks.com/python/databricks-ai-bridge/latest/databricks_langchain.html for more information.
+        """
+        warnings.warn(
+            "get_langchain_chat_open_ai_client() is deprecated. Please install the databricks-langchain package "
+            "and use 'from databricks_langchain import ChatDatabricks' instead. "
+            "See https://pypi.org/project/databricks-langchain/ for more information.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         try:
             from langchain_openai import ChatOpenAI
         except Exception:

tests/test_open_ai_mixin.py

@@ -1,4 +1,5 @@
 import sys
+import warnings
 from io import BytesIO
 
 import pytest
@@ -81,15 +82,36 @@ def test_open_ai_client_prevents_reserved_param_override(monkeypatch):
 
 @pytest.mark.skipif(sys.version_info < (3, 8), reason="Requires Python > 3.7")
 def test_langchain_open_ai_client(monkeypatch):
+    from unittest.mock import MagicMock, Mock
+
     from databricks.sdk import WorkspaceClient
 
     monkeypatch.setenv("DATABRICKS_HOST", "test_host")
     monkeypatch.setenv("DATABRICKS_TOKEN", "test_token")
-    w = WorkspaceClient(config=Config())
-    client = w.serving_endpoints.get_langchain_chat_open_ai_client("databricks-meta-llama-3-1-70b-instruct")
 
-    assert client.openai_api_base == "https://test_host/serving-endpoints"
-    assert client.model_name == "databricks-meta-llama-3-1-70b-instruct"
+    # Mock the langchain_openai import
+    mock_chat_openai = Mock()
+    mock_chat_openai.return_value = MagicMock(
+        openai_api_base="https://test_host/serving-endpoints", model_name="databricks-meta-llama-3-1-70b-instruct"
+    )
+
+    # Mock the module import
+    import sys
+
+    mock_module = MagicMock()
+    mock_module.ChatOpenAI = mock_chat_openai
+    sys.modules["langchain_openai"] = mock_module
+
+    try:
+        w = WorkspaceClient(config=Config())
+        client = w.serving_endpoints.get_langchain_chat_open_ai_client("databricks-meta-llama-3-1-70b-instruct")
+
+        assert client.openai_api_base == "https://test_host/serving-endpoints"
+        assert client.model_name == "databricks-meta-llama-3-1-70b-instruct"
+    finally:
+        # Clean up the mock module
+        if "langchain_openai" in sys.modules:
+            del sys.modules["langchain_openai"]
 
 
 def test_http_request(w, requests_mock):
@@ -115,3 +137,73 @@ def test_http_request(w, requests_mock):
     assert requests_mock.called
     assert response.status_code == 200  # Verify the response status
     assert response.text == "The request was successful"  # Ensure the response body matches the mocked data
+
+
+def test_get_open_ai_client_deprecation_warning(monkeypatch):
+    """Test that get_open_ai_client raises a DeprecationWarning."""
+    from databricks.sdk import WorkspaceClient
+
+    monkeypatch.setenv("DATABRICKS_HOST", "test_host")
+    monkeypatch.setenv("DATABRICKS_TOKEN", "test_token")
+    w = WorkspaceClient(config=Config())
+
+    with warnings.catch_warnings(record=True) as warning_list:
+        warnings.simplefilter("always")
+        client = w.serving_endpoints.get_open_ai_client()
+
+        # Verify a DeprecationWarning was raised
+        assert len(warning_list) == 1
+        assert issubclass(warning_list[0].category, DeprecationWarning)
+        assert "get_open_ai_client() is deprecated" in str(warning_list[0].message)
+        assert "databricks-openai" in str(warning_list[0].message)
+        assert "DatabricksOpenAI" in str(warning_list[0].message)
+
+        # Verify the client still works
+        assert client.base_url == "https://test_host/serving-endpoints/"
+        assert client.api_key == "no-token"
+
+
+@pytest.mark.skipif(sys.version_info < (3, 8), reason="Requires Python > 3.7")
+def test_get_langchain_chat_open_ai_client_deprecation_warning(monkeypatch):
+    """Test that get_langchain_chat_open_ai_client raises a DeprecationWarning."""
+    from unittest.mock import MagicMock, Mock
+
+    from databricks.sdk import WorkspaceClient
+
+    monkeypatch.setenv("DATABRICKS_HOST", "test_host")
+    monkeypatch.setenv("DATABRICKS_TOKEN", "test_token")
+
+    # Mock the langchain_openai import
+    mock_chat_openai = Mock()
+    mock_chat_openai.return_value = MagicMock(
+        openai_api_base="https://test_host/serving-endpoints", model_name="databricks-meta-llama-3-1-70b-instruct"
+    )
+
+    # Mock the module import
+    import sys
+
+    mock_module = MagicMock()
+    mock_module.ChatOpenAI = mock_chat_openai
+    sys.modules["langchain_openai"] = mock_module
+
+    try:
+        w = WorkspaceClient(config=Config())
+
+        with warnings.catch_warnings(record=True) as warning_list:
+            warnings.simplefilter("always")
+            client = w.serving_endpoints.get_langchain_chat_open_ai_client("databricks-meta-llama-3-1-70b-instruct")
+
+            # Verify a DeprecationWarning was raised
+            assert len(warning_list) == 1
+            assert issubclass(warning_list[0].category, DeprecationWarning)
+            assert "get_langchain_chat_open_ai_client() is deprecated" in str(warning_list[0].message)
+            assert "databricks-langchain" in str(warning_list[0].message)
+            assert "ChatDatabricks" in str(warning_list[0].message)
+
+            # Verify the client still works
+            assert client.openai_api_base == "https://test_host/serving-endpoints"
+            assert client.model_name == "databricks-meta-llama-3-1-70b-instruct"
+    finally:
+        # Clean up the mock module
+        if "langchain_openai" in sys.modules:
+            del sys.modules["langchain_openai"]