databricks-openai 0.15.0 import fails with databricks-vectorsearch 0.74: cannot import VectorSearchIndex

[mdbecker]

Summary

I also submitted this to the community hub since it's unclear if these github issues are actively monitored and triaged.

from databricks_openai import DatabricksOpenAI fails in a clean Python 3.12 environment after installing databricks-openai==0.15.0 with normal dependency resolution.

On a fresh install, databricks-openai==0.15.0 resolves databricks-vectorsearch==0.74. Importing DatabricksOpenAI then eagerly imports VectorSearchRetrieverTool, which imports VectorSearchIndex from databricks.vector_search.client. In databricks-vectorsearch==0.74, that symbol does not appear to be available; the documented/public compatibility import appears to be VectorSearchClient.

pip check reports no broken requirements.

This appears to be more than a local compatibility issue: the default installation path for an official Databricks package currently produces a broken import in a clean environment. That raises a broader concern about release hygiene, CI coverage, source-code traceability, issue-tracker ownership, and whether these packages are suitable for production use without strict downstream pinning and independent smoke testing.

Environment

python --version
# Python 3.12.x

python -m pip show databricks-openai databricks-vectorsearch databricks-ai-search databricks-sdk openai
# databricks-openai==0.15.0
# databricks-vectorsearch==0.74
# databricks-ai-search==0.73
# databricks-sdk==0.94.0
# openai==2.41.0

python -m pip check
# No broken requirements found.

Minimal reproduction

python -m venv /tmp/db-openai-repro
source /tmp/db-openai-repro/bin/activate
python -m pip install --upgrade pip
python -m pip install databricks-openai==0.15.0
python -m pip show databricks-openai databricks-vectorsearch databricks-ai-search
python -m pip check

python - <<'PY'
from databricks_openai import DatabricksOpenAI
print(DatabricksOpenAI)
PY

Expected behavior

from databricks_openai import DatabricksOpenAI succeeds.

Actual behavior

ImportError: cannot import name 'VectorSearchIndex' from 'databricks.vector_search.client'

Traceback excerpt:

from databricks_openai import DatabricksOpenAI
...
from databricks_openai.vector_search_retriever_tool import VectorSearchRetrieverTool
...
from databricks.vector_search.client import VectorSearchIndex
ImportError: cannot import name 'VectorSearchIndex' from 'databricks.vector_search.client'. Did you mean: 'VectorSearchClient'?

Notes

Pinning databricks-vectorsearch<0.74 resolves the import failure locally:

python -m pip install "databricks-vectorsearch<0.74"
python - <<'PY'
from databricks_openai import DatabricksOpenAI
print("OK", DatabricksOpenAI)
PY

This suggests a compatibility issue between databricks-openai==0.15.0 and the currently resolved databricks-vectorsearch==0.74, or an eager import issue where importing DatabricksOpenAI requires vector-search retriever dependencies even when only the OpenAI client functionality is needed.

More broadly, this makes the package difficult to trust in production. A clean install resolves successfully, pip check passes, but the top-level documented import fails immediately. If these packages are not actively maintained or not recommended for production use, it would be very helpful for the PyPI pages and Databricks documentation to state that clearly and point users to the recommended supported alternative.

Production-readiness and source-of-truth concerns

There also appears to be a broader source-of-truth and maintenance-signaling problem across these packages.

databricks-vectorsearch has had multiple June 2026 releases, including 0.73 and 0.74, but the PyPI page does not clearly point to a GitHub repository or issue tracker. databricks-ai-search similarly does not make it obvious from PyPI where the source code, release process, or issue tracker lives.

If databricks/databricks-ai-bridge is the source repository used to publish databricks-vectorsearch or databricks-ai-search, that is not clear from the PyPI pages. It is also difficult to reconcile with the visible commit history: at the time of writing, databricks-vectorsearch has had June 2026 PyPI releases, while the latest visible commit on databricks/databricks-ai-bridge appears to be from May 13, 2026.

If those packages are built from some other internal or public repository, please link that repository from PyPI and from the relevant Databricks documentation. Without clear source links, users cannot tell:

• where the published package code comes from;
• where bugs should be reported;
• whether GitHub issues in this repository are monitored by the owners of the released packages;
• whether the PyPI package, GitHub source, and Databricks documentation are actually in sync;
• whether these packages are production-supported or best-effort examples.

This ambiguity is especially concerning because these are not merely community packages. They are Databricks-published packages used with a commercial platform. Production users need a clear support and maintenance story, not just a package name on PyPI.

The open issue backlog in this repository also makes it hard to know whether filing GitHub issues here is the right escalation path. If GitHub issues are not actively monitored or are not the support mechanism for these packages, please state that explicitly and direct users to the appropriate channel.

Suggested fix

One or more of:

1. Update databricks_openai.vector_search_retriever_tool to import/use the current vector search / AI Search API symbol.
2. Relax eager imports in databricks_openai.__init__ so importing DatabricksOpenAI does not require vector-search retriever dependencies to import successfully.
3. Add an upper bound or compatibility constraint on databricks-vectorsearch until the symbol mismatch is fixed.
4. Release a patch version of databricks-openai, for example 0.15.1, that prevents normal dependency resolution from installing a broken dependency set.
5. Update CI/CD to verify from databricks_openai import DatabricksOpenAI does not fail before releasing new versions to PyPI.
6. Add a scheduled nightly CI job that creates a fresh environment, installs the latest released PyPI packages with normal dependency resolution, and runs basic import/smoke tests. This would catch breakages caused by newly released transitive dependencies even when no code has changed in this repository.
7. Clarify whether databricks-openai, databricks-vectorsearch, and databricks-ai-search are production-supported packages.
8. Clarify where users should file issues for each of these packages.
9. Add clear source repository and issue tracker links to the PyPI pages for databricks-vectorsearch and databricks-ai-search.
10. If databricks/databricks-ai-bridge is not the source of truth for these packages, update the documentation and PyPI metadata so users can find the actual source of truth.
11. If these packages are deprecated, experimental, or not maintained with production-level compatibility guarantees, add explicit warnings to the PyPI pages and Databricks docs.

[kdshreyas]

Can confirm I'm hitting the same issue.

Using Claude models on Databricks Serverless. The issue shows up with databricks-vectorsearch 0.74, and pinning to <0.74 avoids it for me.

Python 3.12.3 and databricks-ai-bridge 0.19.0.

[mdbecker]

Quick update, it looks like your own GitHub actions also catch this issue (see here for example)

[kunyuchen]

Thanks for reporting. We have released databricks-openai v0.16.0 and databricks-ai-bridge v0.20.0 to fix the issue.
Please let us know if you encounter further issues.