{"id":4492,"library":"databricks-openai","title":"Databricks OpenAI Integration","description":"The `databricks-openai` package provides seamless integration of Databricks AI features into OpenAI applications. It extends the standard OpenAI client with Databricks authentication and offers specialized tools like `VectorSearchRetrieverTool` for interacting with Databricks' AI capabilities. Currently at version 0.14.0, it sees active development, with frequent updates to support new OpenAI models and Databricks features.","status":"active","version":"0.14.0","language":"en","source_language":"en","source_url":"https://github.com/databricks/databricks-ai-bridge/tree/main/integrations/openai","tags":["databricks","openai","llm","ai","vector-search","tools","mlops"],"install":[{"cmd":"pip install databricks-openai openai","lang":"bash","label":"Install core packages"},{"cmd":"pip install databricks-openai[memory]","lang":"bash","label":"Install with memory support (optional)"}],"dependencies":[{"reason":"The library integrates with and extends the OpenAI Python SDK, making it a de-facto requirement for most use cases.","package":"openai"},{"reason":"Commonly used for Databricks workspace authentication and management, though not a direct dependency of databricks-openai itself.","package":"databricks-sdk","optional":true}],"imports":[{"note":"This client extends the standard OpenAI client with Databricks authentication, automatically handling credentials.","symbol":"DatabricksOpenAI","correct":"from databricks_openai import DatabricksOpenAI"},{"note":"Provides a utility class to create a vector search-based retrieval tool for querying indexed embeddings on Databricks.","symbol":"VectorSearchRetrieverTool","correct":"from databricks_openai import VectorSearchRetrieverTool"},{"note":"Re-exported from the Unity Catalog integration, simplifies interaction with MCP servers and Unity Catalog functions.","symbol":"UCFunctionToolkit","correct":"from databricks_openai import UCFunctionToolkit"}],"quickstart":{"code":"import os\nfrom databricks_openai import DatabricksOpenAI, VectorSearchRetrieverTool\nfrom openai.types.chat import ChatCompletionMessageParam\n\n# Ensure your Databricks host and token are set as environment variables\n# DATABRICKS_HOST='https://<your-workspace-url>.cloud.databricks.com'\n# DATABRICKS_TOKEN='dapi...'\n\n# Initialize the Databricks OpenAI client\n# It automatically picks up DATABRICKS_HOST and DATABRICKS_TOKEN from environment variables\n# or Databricks CLI configuration.\nclient = DatabricksOpenAI(\n    host=os.environ.get('DATABRICKS_HOST', ''),\n    token=os.environ.get('DATABRICKS_TOKEN', '')\n)\n\n# Example 1: Simple chat completion using a Databricks-hosted model\ntry:\n    chat_completion = client.chat.completions.create(\n        model=\"databricks-gpt-5-mini\", # Or your specific Databricks-hosted endpoint name\n        messages=[\n            {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n            {\"role\": \"user\", \"content\": \"What is Databricks Unity Catalog?\"}\n        ]\n    )\n    print(\"\\n--- Simple Chat Completion ---\")\n    print(f\"Assistant: {chat_completion.choices[0].message.content}\")\nexcept Exception as e:\n    print(f\"Error during simple chat completion: {e}\")\n\n# Example 2: Chat completion with a Vector Search Retriever Tool\n# Replace 'catalog.schema.my_index_name' with your actual Vector Search index name\nindex_name = os.environ.get('DATABRICKS_VECTOR_SEARCH_INDEX', 'catalog.schema.my_index_name')\n\ntry:\n    dbvs_tool = VectorSearchRetrieverTool(index_name=index_name)\n    \n    messages: list[ChatCompletionMessageParam] = [\n        {\"role\": \"system\", \"content\": \"You are a helpful assistant that uses provided tools.\"},\n        {\"role\": \"user\", \"content\": \"Using the Databricks documentation, what is Spark?\"}\n    ]\n\n    first_response = client.chat.completions.create(\n        model=\"databricks-gpt-5-mini\",\n        messages=messages,\n        tools=[dbvs_tool.tool]\n    )\n\n    print(\"\\n--- Chat Completion with Tool ---\")\n    tool_call = first_response.choices[0].message.tool_calls[0]\n    if tool_call.function.name == dbvs_tool.tool.function.name:\n        args = json.loads(tool_call.function.arguments)\n        # In a real scenario, this would execute on Databricks\n        # For demonstration, we simulate a response\n        # result = dbvs_tool.execute(query=args[\"query\"])\n        result = {\"docs\": [{\"text\": \"Apache Spark is an open-source, distributed processing system used for big data workloads.\"}]}\n        \n        messages.append(first_response.choices[0].message)\n        messages.append({\"role\": \"tool\", \"tool_call_id\": tool_call.id, \"content\": json.dumps(result)})\n        \n        second_response = client.chat.completions.create(\n            model=\"databricks-gpt-5-mini\",\n            messages=messages,\n            tools=[dbvs_tool.tool] # Tools should still be passed for the second turn\n        )\n        print(f\"Assistant (using tool): {second_response.choices[0].message.content}\")\n    else:\n        print(f\"Assistant: {first_response.choices[0].message.content}\")\n\nexcept Exception as e:\n    print(f\"Error during tool usage: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the `DatabricksOpenAI` client for basic chat completions and how to use the `VectorSearchRetrieverTool` to integrate Databricks Vector Search capabilities into an OpenAI-compatible agent workflow. Ensure `DATABRICKS_HOST` and `DATABRICKS_TOKEN` environment variables are set for authentication."},"warnings":[{"fix":"No action needed, the client handles this automatically. Be aware of this behavior if debugging tool definitions for non-GPT models.","message":"When using `DatabricksOpenAI` with non-GPT models (e.g., Claude, Llama) for tool calls, the client automatically strips the 'strict' field from tool definitions. These models do not support this OpenAI-specific parameter, and manual removal is not required.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Increase TPM limits in your Databricks or Azure OpenAI configuration, reduce payload size, use libraries like `TikToken` for token estimation, and implement exponential backoff retry logic in your application.","message":"Encountering '429 Too Many Requests' errors (rate limiting) is common when processing large datasets with OpenAI APIs via Databricks. This indicates exceeding the allowed tokens per minute (TPM) or requests per minute (RPM).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your prompts for potential policy violations, break large prompts into smaller chunks, and consider setting the `failOnError` parameter to `false` in `AI_QUERY` to gracefully capture errors without interrupting workflow.","message":"Failures with SQL `AI_QUERY` function, particularly the `[REMOTE_FUNCTION_HTTP_FAILED_ERROR]` (SQLSTATE: 57012), can indicate issues like prompt policy violations or internal operational problems with certain OpenAI models.","severity":"gotcha","affected_versions":"All versions using `AI_QUERY`"},{"fix":"Thoroughly verify endpoint names in both your code and the Databricks UI, ensure API keys and any secret configurations are correct, and confirm that the user or service principal has the necessary access to the serving endpoint. Check Databricks serving endpoint logs for detailed error messages.","message":"Common 500-level errors when invoking models via Databricks often stem from mismatches in endpoint names, incorrect API keys, resource names, deployment names, or insufficient permissions. This applies to both `databricks-openai` and other integration packages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using these unsupported parameters when interacting with Databricks pay-per-token foundation models. Consult the Databricks documentation for supported parameters for your specific model type.","message":"When using the OpenAI Responses API on Databricks, specific parameters like `background`, `store`, `previous_response_id`, and `service_tier` are not supported for pay-per-token foundation models. External models generally support all parameters.","severity":"gotcha","affected_versions":"All versions using OpenAI Responses API"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}