模型配置

在 DeepSeek Harness 的架构体系中，模型作为提供推理与认知决策的“大脑”，通过标准化的 Provider 适配层 无缝接入执行中枢。Harness 既支持开箱即用的 DeepSeek 官方模型与主流云厂商目录，也支持通过统一网关接入企业私有模型、Ollama 本地实例及多模态视觉模型。

本文将详细介绍如何在 Web UI 控制台及配置文件中完成模型提供方的配置、凭证管理与多模态参数设定。

配置 DeepSeek 官方模型#

DeepSeek 是 Harness 原生深度优化的核心模型提供方，具备极高的 Prefix Cache 命中率与超低推理延迟。

操作步骤

1. 打开 Web UI 控制台，点击左下角 设置 (Settings) → 模型 (Models)；
2. 在模型列表中找到 DeepSeek 卡片；
3. 填入你的 API 密钥 (API Key)：sk-xxxxxxxxxxxxxxxxxxxxxxxx；
4. 点击 保存 (Save) 即可完成配置。

运行时热生效与安全存储

• 即时生效：所有模型配置变更会在下一次 Agent 请求时立即生效，无需重启后台服务；
• 凭证安全隔离：API Key 会自动加密写入本地 $DSH_HOME/.credentials.yaml 存储文件中，Web 界面只保留脱敏引用，杜绝明文泄露风险。

添加目录内置提供方 (Catalog Providers)#

除了 DeepSeek 官方直连，Harness 内置支持了主流国际大模型服务商目录（如 Anthropic、OpenAI、Groq 等）：

配置常规云端提供商

1. 在 模型 (Models) 设置页，点击 “添加提供方” (Add provider) 按钮；
2. 从下拉目录中选择目标服务商（如 OpenAI 或 Anthropic）；
3. 填入对应的 API Key 并保存。

原生云厂商凭证说明 (AWS Bedrock / Azure / Google Vertex)

对于采用云厂商企业级 IAM 认证的提供方：

• 仅填写通用 API Key 无法通过鉴权；
• 需在凭据表单中提供对应的原生凭证，例如 AWS 区域 (Region)、Azure 资源名称 (Resource Name) 或 Google Cloud 项目 ID (Project ID)。

添加自定义与本地提供方 (Custom & Local Providers)#

对于企业内部反向代理网关、自建中继服务，或者使用 Ollama / vLLM / LocalAI 在本地机器私有化运行的开源模型，可通过自定义提供方接入。

配置自定义提供方必填项

选择 “添加自定义提供方” (Add a custom provider)，依次配置以下核心要素：

典型场景：接入本地 Ollama 实例

在本地启动 Ollama 服务后（默认端口 11434），在 Harness 中添加如下自定义配置：

• Provider ID: ollama
• Base URL: http://localhost:11434/v1
• Protocol: openai-compatible
• Models: qwen2.5-coder:32b, deepseek-r1:14b

多模态视觉模型与图片输入声明 (Image Input)#

默认情况下，手动添加的自定义模型会被识别为纯文本模型 (Text-only)。如果你的模型具备多模态图像感知能力（如 gpt-4o, claude-3-5-sonnet, qwen-vl-max），需要显式声明图片输入支持。

在 $DSH_HOME/settings.yaml 配置文件中为目标模型添加 input 属性：

# $DSH_HOME/settings.yaml
llm-pi-ai:
  providers:
    my-custom-gateway:
      baseUrl: 'https://api.example.com/v1'
      models:
        - id: 'qwen-vl-max'
          input: [text, image]    # 显式声明支持文本与图像双模态
        - id: 'deepseek-chat'
          input: [text]           # 纯文本模型

配置后，Agent 在接收到用户上传的截图、架构拓扑图或报错界面时，会自动将图片按 Base64 或预签名 URL 编码注入多模态提示流中。

声明式配置文件管理 (适用于 Docker 与 Headless 运维)#

在容器化部署或 CI/CD 自动化评测场景中，可以通过编辑 $DSH_HOME/settings.yaml 或工程根目录下的 cordis.yml 进行声明式配置：

# cordis.yml 声明式模型配置示例
plugins:
  # LLM 核心适配层
  '@deepseek-ai/dsh-plugin-llm-adapter':
    defaultProvider: 'deepseek'
    providers:
      deepseek:
        apiKey: 'env(DEEPSEEK_API_KEY)'
        defaultModel: 'deepseek-chat'
        models:
          - id: 'deepseek-chat'
            displayName: 'DeepSeek-V3 (通用编码)'
          - id: 'deepseek-reasoner'
            displayName: 'DeepSeek-R1 (深度推理)'
      
      ollama-local:
        baseUrl: 'http://localhost:11434/v1'
        models:
          - id: 'deepseek-r1:14b'

    # 全局重试与超时控制
    timeout: 60000
    maxRetries: 3

常见问题与排错#

Q1: 修改或新增模型配置后，需要重启 Web UI 吗？

解答：完全不需要重启。DeepSeek Harness 内部基于响应式的微内核架构设计，所有模型提供方的配置改动都会被事件总线实时捕获并动态广播。当你在 Web UI 设置面板中修改了 API 密钥、切换了默认模型或添加了新的自定义接口并点击保存后，下一次向 Agent 发送指令或发起新对话时，系统就会自动平滑读取最新的配置凭据并建立连接。即使当前有正在运行的思考任务，系统也会在当前执行轮次结束后无缝衔接新配置，无需繁琐地去终端重启后台服务。

Q2: 如何接入本地运行的 Ollama 或私有大模型？

解答：接入本地私有模型非常简单，只需在设置页面点击“添加自定义提供方”即可完成。首先为该提供方设置一个容易识别的名称标识（例如 ollama-local），然后在 Base URL 基础地址栏中填入本地 Ollama 服务的监听地址，通常为 http://localhost:11434/v1（请特别注意末尾要包含 /v1，以匹配通用标准接口规范）。接着在接口协议中选择 OpenAI 兼容格式，凭证一栏留空或随意输入占位字符，最后在模型列表中填入你已经在本地拉取好的模型名称（例如 deepseek-r1:14b 或 qwen2.5-coder:32b）并保存。这样 Agent 的所有推理计算都会在你的本地显卡或 CPU 上离线运行，不仅免去了云端 Token 费用，还能确保企业代码和私有文档绝对不出本地。

Q3: 遇到模型服务报 429 限流或请求超时怎么办？

解答：429（Too Many Requests）通常代表大模型服务商对单个 API 密钥设置了每分钟请求次数或并发 Token 上限，当 Agent 在执行复杂的长文本分析、深度逻辑推导或多轮代码重构时，短时间内调用较为密集便可能触发频控。针对这种情况，Harness 内置了智能自愈机制：一方面系统支持在本地配置文件中开启指数退避自动重试，遇到限流时会在后台自动等待几秒后重新发送，无需手动干预；另一方面，你可以在设置中配置多条提供方通道作为备用节点，将云端 DeepSeek 作为主力通道，同时配置本地模型或备用服务商作为兜底。一旦主力通道由于配额耗尽触发限流，Harness 会自动平滑切换到备用模型继续执行，确保你的长时间自动化任务不会中途报错中断。

Q4: 填写的 API 密钥安全吗？会被上传吗？

解答：非常安全，完全不必担心泄漏。DeepSeek Harness 严格践行“本地优先、凭证与代码彻底解耦”的安全架构。你在 Web UI 中输入的所有 API Key 只会被加密持久化保存在你当前个人电脑的主目录凭据文件（$DSH_HOME/.credentials.yaml）中，浏览器前端界面呈现的仅仅是经过脱敏处理的引用标记。即使未来你需要将项目目录打包分享给团队成员，或者将工作区代码提交到 GitHub 等公共代码仓库，被提交的也仅仅是声明式配置文件中的环境变量占位符，真实的私钥永远留在你个人的本地机器中，任何第三方外部服务器或云端平台都无法窥探到你的真实凭据。