zhuchengde0214-ctrl/dsh-llm-databricks

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-.tgz 检查 tarball 只能包含
构建后的 lib、bundle patch、package metadata、README、CHANGELOG 和 LICENSE。
随后把 tarball 安装到隔离 DSH_HOME，先执行 --dump-config 再发布。

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

License

MIT