dsh-llm-databricks

English

这是一个独立、由社区维护的 DeepSeek Harness Databricks AI Gateway 对话模型 bundle。它以 out-of-tree 插件安装，只使用 Harness 公共的 LLM/settings/credentials seam，不修改 Harness，也不 monkey-patch node_modules。

> 本包不是 DeepSeek AI 或 Databricks 官方产品。

支持矩阵

Databricks 路由	`protocol`	流式	工具	说明
MLflow Chat Completions `/ai-gateway/mlflow/v1/chat/completions`	`mlflow-chat`	是	是	OpenAI Chat 线协议；删除不兼容的 `store` 和工具 `strict`。可承载 Databricks 上的 Claude、GPT、Gemini、Llama、DeepSeek 等对话模型。
MLflow Responses `/ai-gateway/mlflow/v1/responses`	`mlflow-responses`	是	是	在 Harness/pi-ai 可表达范围内使用 Responses/OpenResponses；删除不兼容的 `store` 和工具 `strict`。
Native Anthropic Messages `/ai-gateway/anthropic/v1/messages`	`anthropic-messages`	是	是	只发送 `Authorization: Bearer`，禁止 `x-api-key`；保留模型支持的文本、tool use 和 thinking 内容。
Native OpenAI Responses `/ai-gateway/openai/v1/responses`	`openai-responses`	是	是	Bearer 鉴权，原生 Responses 线协议。

0.1.0 不实现 native Gemini API 和 embeddings。Gemini 对话模型已经可以通过 MLflow Chat Completions 使用；Harness 当前 LLM seam 不消费 embeddings。 Native Gemini 属于 roadmap。

环境要求

Node.js ^22.19.0 或 >=24
与 DeepSeek Harness 0.1.0-rc.7 兼容的公共 seam
配置的 workspace gateway 接受的 Databricks bearer token

安装

npm 公开发布后：

dsh plugin --profile web add dsh-llm-databricks

从公开 GitHub 仓库安装：

dsh plugin --profile web add github:zhuchengde0214-ctrl/dsh-llm-databricks

从本地 tarball 安装：

pnpm pack
dsh plugin --profile web add ./dsh-llm-databricks-0.1.0.tgz

dsh.bundle.patch 只加入一个默认休眠的 llm-databricks 插件行；只有配置 provider 后才注册路由。

配置

在隔离 profile 的用户 settings 中加入独立的 llm-databricks namespace，也可通过写入同一 namespace 的 Harness 配置界面完成：

llm-databricks:
  providers:
    databricks-main:
      displayName: Databricks Main
      workspaceUrl: https://dbc-example.cloud.databricks.com
      protocol: mlflow-chat
      credentialRef: DATABRICKS_TOKEN
      models:
        - id: example-chat-endpoint
          name: Example Chat Model
          contextWindow: 128000
          maxTokens: 8192
          input: [text]
        - id: example-reasoning-endpoint
          name: Example Reasoning Model
          contextWindow: 200000
          maxTokens: 16384
          reasoningEfforts:
            off:
            low: low
            high: high

id 是请求中发送的模型服务/serving endpoint 标识。容量信息必须与实际部署一致。input 默认 [text]；只有 endpoint 确实支持图片时才声明 [text, image]。

同一 workspace 使用多个协议时，为每种协议配置独立 provider：

llm-databricks:
  providers:
    databricks-anthropic:
      workspaceUrl: https://adb-example.azuredatabricks.net
      protocol: anthropic-messages
      credentialRef: DATABRICKS_TOKEN
      models:
        - id: example-anthropic-endpoint
          contextWindow: 200000
          maxTokens: 16384
    databricks-responses:
      workspaceUrl: https://workspace.gcp.databricks.com
      protocol: openai-responses
      credentialRef: DATABRICKS_TOKEN
      models:
        - id: example-responses-endpoint
          contextWindow: 128000
          maxTokens: 8192

Token 应通过 Harness credentials service（例如 Web Models 页面）保存，或在启动 Harness 的进程环境中提供对应变量。settings 只保存 credentialRef；插件不会把 token 写入 settings 或日志。

不发送模型请求即可检查 bundle 合成结果：

dsh --profile web --dump-config

安全边界

强制 HTTPS；workspaceUrl 禁止 userinfo、路径、query 和 fragment。
默认只向 .cloud.databricks.com、.azuredatabricks.net、

.gcp.databricks.com 或旧版 .databricks.net 下的 workspace 子域发送 bearer。匹配按 DNS label 边界进行，会拒绝 lookalike suffix。

官方 host 只允许 443 端口。
每种协议固定到准确的 gateway 请求路径，并禁用请求重定向。
私有/自定义域必须显式设置 allowCustomHost: true。这意味着允许向该

hostname 转发 bearer；启用前必须审查 DNS 所有权、TLS 终止、代理和日志。

自定义域使用非 443 端口时还必须设置

allowNonStandardPort: true，主要用于受控私有 gateway 和测试。

Native Anthropic 会删除 x-api-key，只发送 bearer。本插件不接管官方

Anthropic 或其他非 Databricks provider。

错误、重试与 429

插件保留 HTTP status、Databricks/request ID，以及有效的 Retry-After/retry-after-ms：

401/403 → 鉴权错误
含 quota、workspace input tokens/minute 等信息的 429 → quota；其他

429 → rate limit

只有明确的 context-length 信息才映射为 context overflow
普通 400 或无 body 的 400 → invalid request，绝不会误报 context overflow
5xx → server failure

SDK 内部重试被关闭，由 Harness provider retry policy 统一处理。默认策略只重试瞬态错误、尊重服务端 delay，并避免确定性 4xx 重试风暴。

遇到 429 时：

1. 读取 retry delay 和 request ID，不要立即重试。 2. 检查 workspace AI Gateway 用量及 serving endpoint 的 input tokens/minute quota。 3. 降低并发 session、prompt 大小或上下文中保留的工具输出。 4. 申请提高 quota，或把负载分散到独立治理的 endpoint。

迁移与卸载

迁移时复制 llm-databricks settings section，并在目标 DSH_HOME 中重新创建同名 credential。不要把 credential value 写入版本控制。

卸载并删除对应 settings section：

dsh plugin --profile web remove dsh-llm-databricks

只有在其他路由不再使用时，才从 credentials service 删除 DATABRICKS_TOKEN。

开发、测试与打包

corepack pnpm install --frozen-lockfile
pnpm run typecheck
pnpm run lint
pnpm test
pnpm run build
pnpm pack --pack-destination .artifacts

测试只使用 stub transport 和随机端口上的隔离 HTTPS mock gateway；CI 不访问真实 Databricks，也不需要真实 credential。

发布前更新 CHANGELOG.md 与版本，运行全部命令，并用 tar -tzf .artifacts/dsh-llm-databricks-<version>.tgz 检查 tarball 只能包含构建后的 lib、bundle patch、package metadata、README、CHANGELOG 和 LICENSE。随后把 tarball 安装到隔离 DSH_HOME，先执行 --dump-config 再发布。

仓库保留 private: false 以便未来公开 npm 发布，但 npm publish 必须由 maintainer 在独立审核后执行。

License

MIT

来源信息

安装

检查来源文件

dsh-llm-databricks

支持矩阵

环境要求

安装

配置

安全边界

错误、重试与 429

迁移与卸载

开发、测试与打包

License

更多相关插件

dsh-hooks-claude-code

dsh-hooks-codex

WeKnora#dsh-weknora