Dify 踩坑记录

知识库

1. 上传 Excel 文件时报 openpyxl 类型错误

报错信息： expected <class 'openpyxl.styles.fills.Fill'>

问题原因： 当 Excel 文件包含复杂的单元格样式（如填充颜色、背景色等）时，openpyxl 在读取 cell.hyperlink 属性时内部样式对象未正确初始化，导致类型转换失败。

可能原因： 该 Excel 文件是从企业微信等平台下载的共享文档，存在格式不兼容情况。

检验方法： 将该文件另存为，查看大小是否发生变化。若变化说明 Excel 内部修正了不正确的样式和格式，使用新文件上传即可。

插件与模型

1. 为火山引擎插件添加不存在的模型

像火山引擎这些模型厂商插件，可能模型更新并不及时，而我们如果想要用到其新的模型，虽然可以通过 OpenAI 兼容插件进行使用，但有些参数该兼容插件并不一定支持，那我们一定要使用某个模型该怎么办？

以 deepseek-v4-flash 为例，截止 2026-07-07，Dify 官方的 火山引擎插件 并没有支持该模型，我们可以通过为插件补充相应的 yaml 描述文件来使其支持

前往 Dify 的 插件市场 下载离线版本插件（.difypkg）结尾的插件

准备好所需要加的模型 yaml 文件，文件结构可参考 官方提供的模型 ，参数可在网上自行查询，这是我提供的一份 deepseek-v4-flash 的样例

model: deepseek-v4-flash
label:
  en_US: deepseek-v4-flash
  zh_Hans: deepseek-v4-flash
model_type: llm
features:
  - agent-thought
  - tool-call
  - stream-tool-call
  - multi-tool-call
model_properties:
  mode: chat
  context_size: 1000000
parameter_rules:
  - name: temperature
    use_template: temperature
  - name: top_p
    use_template: top_p
  - name: max_tokens
    use_template: max_tokens
  - name: thinking
    label:
      zh_Hans: 深度思考模式
      en_US: Thinking Mode
    type: string
    required: false
    default: enabled
    options:
      - enabled
      - disabled
    help:
      zh_Hans: 启用后模型会在回答前进行系统性分析和多步骤规划，适用于复杂推理任务。
      en_US: When enabled, the model performs systematic analysis and multi-step planning before answering, suitable for complex reasoning tasks.

使用解压缩软件直接打开刚刚下载的 .difypkg 包，并找到 models/llm/_position.yaml 文件，将其复制出来

在适当位置补充 deepseek-v4-flash 字段，使其在模型厂商配置页面按指定顺序进行展示

然后将修改后的 _position.yaml 和 新增的 deepseek-v4-flash.yaml 文件直接拖动到压缩包中进行覆盖和新增。注意：一定不要解压和再压缩

前往 Dify 系统进行离线安装插件，即可在配置处找到对应的配置：

补充：该方法只是一个快速和比较懒人的做法，如果你是开发者，完全可以通过 dify-plugin 来进行重打包