【HarmonyOS学习笔记】2026-08-04 | DevEco Code 接入 DeepSeek 自定义模型

---

date: 2026-08-04
tags: [HarmonyOS, DevEco Code, DeepSeek, LLM配置, 踩坑]
type: 问题记录

1️⃣ 现象（发生了什么？）

在 DevEco Code 的模型选择器中切到 DeepSeek 模型（deepseek-v4-flash），发消息时报错：ProviderModelNotFoundError。

模型不在已注册模型列表里，DevEco Code 根本不认识这个模型。

2️⃣ 解决办法（我是怎么做的？）

第一次尝试：/connect 配置 API key（失败）

我尝试在 DevEco Code 中用 /connect 命令添加 DeepSeek 的 API key。

/connect 配置后，auth.json 里出现了 deepseek provider 的认证信息，但模型依然不可用，还是报 ProviderModelNotFoundError。

这里的认知误区：我以为"配置了 API key = 注册了模型"。实际上 /connect 只做了认证，没有注册模型定义。

查官方文档

查到官方文档（2026-07-21 更新）提供了两种配置方式：

1. /connect 命令：配置 provider 的认证（API key）
2. deveco.jsonc 文件：注册 provider 和模型定义

第二次尝试：deveco.jsonc 注册模型（成功）

在 deveco.jsonc 中新增 provider.deepseek 配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "deepseek": {
      "api": "openai",
      "name": "DeepSeek",
      "options": {
        "baseURL": "https://api.deepseek.com"
      },
      "models": {
        "deepseek-v4-flash": {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "tool_call": true,
          "temperature": true,
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

重启 DevEco Code 后，DeepSeek 模型可用。

设计取舍：独立 provider，不动内置

我选择新建独立的 deepseek provider，而不是在官方示例的 deveco provider 里加模型、覆盖 baseURL。

原因：DevEco Code 内置的 GLM-5.1 等模型走 deveco provider（OAuth 认证），如果在同一个 provider 里混入 DeepSeek（API key 认证），认证方式不匹配；改 baseURL 还可能影响内置模型。

独立 provider 方案：DeepSeek 和 GLM-5.1 互不干扰，可以随时来回切换。

3️⃣ 为什么能解决？（刨根问底）

📖 官方怎么说

官方文档描述了两种配置方式：/connect 命令（认证）和 deveco.jsonc（模型定义）。

🧠 我的理解

核心认知：认证 ≠ 模型定义，两者是分离的。

配置项	文件	作用
API key（认证）	auth.json	证明"这个 provider 我有权限调用"
模型定义（注册）	deveco.jsonc	告诉 DevEco Code “这个模型存在，怎么调、叫什么名”

/connect 只写了 auth.json（认证），没写 deveco.jsonc（模型定义），所以 DevEco Code 拿到 key 也不知道 deepseek-v4-flash 是什么——报 ProviderModelNotFoundError。

provider name 是两者的关联键：auth.json 里 deepseek 的 API key，会自动关联到 deveco.jsonc 里 provider.deepseek 的模型定义。所以 deveco.jsonc 里不用重复写 key，key 也不会出现在配置文件中。

api 字段：官方示例里没有这个字段，可能是 LLM 适配器简写标识符，我用 "openai" 后工作正常（DeepSeek 兼容 OpenAI 接口格式）。

4️⃣ 验证

场景一：DeepSeek 配置生效

重启后查 DevEco Code 日志：

llm.runtime=ai-sdk llm.provider=deepseek llm.model=deepseek-v4-flash
message=stream providerID=deepseek modelID=deepseek-v4-flash

DeepSeek 模型被成功识别，流式对话和工具调用（read/grep）都正常往返。之前对话当前会话就运行在 deepseek-v4-flash 上，多轮流式请求无报错。

结论：✅ 配置生效，ProviderModelNotFoundError 消失。

场景二：GLM-5.1 回归验证

切回 GLM-5.1 后查日志：

message=stream providerID=deveco modelID=GLM-5.1
llm.provider=deveco llm.model=GLM-5.1

结论：✅ 内置 GLM-5.1 不受影响，独立 provider 方案设计正确，双模型来回切换零问题。

场景三：小插曲

日志里有个 Failed to fetch models.dev（拉取开源模型目录超时），这个是 DevEco Code 的网络问题，与本次配置无关，不影响使用。

5️⃣ 最终结论（最佳实践）

维度	建议
配置新模型	/connect 配认证 + deveco.jsonc 注册模型定义，两步缺一不可
provider 隔离	自定义模型用独立 provider，不动内置 provider，互不干扰
改配置后	必须重启 DevEco Code，配置不热加载
api 字段	OpenAI 兼容模型用 "openai" 即可
认证关联	按 provider name 自动关联，配置文件不写 key
失败排查	报 ProviderModelNotFoundError = 模型没注册；认证问题另行排查

// 最佳实践：独立 provider 注册自定义模型
{
  "provider": {
    "deepseek": {
      "api": "openai",
      "name": "DeepSeek",
      "options": { "baseURL": "https://api.deepseek.com" },
      "models": {
        "deepseek-v4-flash": { "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash" }
      }
    }
  }
}

核心原则： 认证（auth.json）与模型定义（deveco.jsonc）分离，/connect 只配认证，注册模型要写 deveco.jsonc，两者按 provider name 自动关联。

---

学习小结：这次踩坑的核心是弄清了 DevEco Code 的模型配置架构——/connect 配置认证（API key 进 auth.json），deveco.jsonc 注册模型定义，两者按 provider name 自动关联，缺一不可。报 ProviderModelNotFoundError 说明模型没注册而非认证失败。自定义模型用独立 provider 隔离内置模型是正确姿势，改配置必须重启生效。

懿路向前 · AI辅助整理
2026-08-04