前言¶
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 使用。
