前言¶
DeepSeek Harness（DSH）开发者在使用 Databricks AI Gateway 部署的模型时，需要一种不侵入框架核心的集成方式。现有的集成方案往往需要修改 Harness 源码或 node_modules，这会破坏版本管理和升级能力。
下面介绍的 dsh-llm-databricks 插件，通过使用 DeepSeek Harness 的公共接口，提供了一个独立的集成方案。它允许开发者直接在 DSH 中调用 Databricks 上通过 AI Gateway 提供的对话模型。
插件定位¶
这是一个社区维护的 DeepSeek Harness 插件，由 zhuchengde0214-ctrl 交付。
其核心价值在于：
* 非侵入式集成：不修改 Harness 核心代码或 node_modules。
* 通用协议支持：适配多种 Databricks Gateway 路由协议。
* 独立安装：以 Out-of-tree 方式安装，不影响主系统稳定性。
安装¶
安装此插件需要满足前置环境要求（详见后文），随后执行以下命令：
dsh plugin --profile web add dsh-llm-databricks
配置与使用¶
插件安装后，会在配置中增加一个 llm-databricks 的配置项。你需要在对应的 Profile（例如 web）的用户设置中添加该配置段。
下面是一个配置示例，展示了如何为不同的协议配置提供者：
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: null
low: low
high: high
配置中：
* workspaceUrl 必须是合法的 HTTPS 地址。
* id 对应模型服务端点的标识符。
* input 默认为 [text]，若端点支持图片，需显式声明 [text, image]。
技术细节与注意事项¶
在使用前，请确认以下环境与安全要求：
运行环境
* Node.js：版本需在 ^22.19.0 或 >=24 之间。
* DeepSeek Harness：需要 0.1.0-rc.7 兼容的接口。
安全与网络
* HTTPS 强制：通信必须使用 HTTPS。workspaceUrl 中的用户信息、查询字符串和片段会被拒绝。
* 域名限制：Bearer 凭证默认仅发送给以下子域名：.cloud.databricks.com、.azuredatabricks.net、.gcp.databricks.com 或传统的 .databricks.net。这基于标签边界安全匹配。
* 端口限制：官方主机必须使用 443 端口。
* 自定义 DNS：若使用私有 DNS，需设置 allowCustomHost: true。
* 非标准端口：若使用非 443 端口，需设置 allowNonStandardPort: true。
协议特性
* 支持 mlflow-chat、mlflow-responses、anthropic-messages 和 openai-responses 四种协议。
* 所有协议均支持流式传输和工具调用。
* Native Anthropic 请求：使用 Bearer 认证，会自动删除 x-api-key 头。
* 重试机制：插件本身禁用了 SDK 重试，由 Harness 的 Provider 重试策略接管。
结语¶
该插件为 DSH 开发者提供了一条清晰、标准的路径来对接 Databricks AI Gateway。通过遵循上述配置步骤和安全规范，你可以在不修改 Harness 核心代码的情况下，将其作为通用 LLM Provider 使用。
