--- dimensions: type: primary: implementation detail: basic level: beginner standard_title: Getting Started New Model language: zh title: 快速接入一个新模型 description: 本文档指导非专业开发者如何为Dify添加新模型，重点在于通过修改配置文件为现有模型供应商添加新型号模型。包括Fork仓库、复制与修改模型配置、更新供应商版本、本地测试以及提交贡献的完整流程。 --- 欢迎来到 Dify 的插件开发世界！Dify 的强大功能离不开社区贡献者的共同努力。我们相信，即使你不是专业的程序员，只要你对 AI 技术充满热情并愿意查阅资料，也能为 Dify 贡献自己的一份力量，例如帮助 Dify 支持更多、更新的 AI 模型。 本文将以最简明的方式，带你完成最常见也最简单的贡献：为一个 Dify **已经支持**的模型供应商，添加一个**新型号**的模型。这种方式通常**只需要修改配置文件**，无需编写代码，非常适合作为你的第一个贡献！ > **相关概念**：在开始前，建议你阅读[模型插件](/plugin-dev-zh/0131-model-plugin-introduction)文档，了解模型插件的基本概念和结构。 **这种快速接入方式适用于：** - 新模型属于 Dify 已有插件支持的供应商（如 OpenAI, Google Gemini, Anthropic Claude 等）。 - 新模型与同系列其他模型使用相同的 API 认证和基础调用逻辑。 - 主要区别在于模型 ID、上下文长度、最大 Token 数、定价等配置参数。 _(如果你需要添加的模型需要新的 API 逻辑或支持特殊功能，那将涉及到 Python 代码编写，请参考 [创建新模型提供者](/plugin-dev-zh/0222-creating-new-model-provider) 获取更详细的指南。)_ **准备工作:** - 熟悉基本的 Git 操作 (Fork, Clone, Pull Request)。 - 一个 GitHub 账号。 - 安装并配置好 Dify 插件开发工具包 (参考 [初始化开发工具](/plugin-dev-zh/0221-initialize-development-tools))。 **操作步骤:** 1. **Fork & Clone 官方插件仓库:** - 访问 Dify 官方插件仓库 `https://github.com/langgenius/dify-official-plugins`。 - 点击 "Fork" 按钮，将仓库复刻到你自己的 GitHub 账号下。 - 使用 Git 将你 Fork 的仓库 Clone 到你的本地电脑。 2. **找到并复制模型配置文件:** - 在本地仓库中，导航到 `models/` 目录下，找到你想要添加模型的供应商文件夹，例如 `vertex_ai`。 - 进入该供应商对应的模型类型子目录，通常是 `models/llm/` (如果是文本生成模型)。 - 在该目录下，找到一个与你要添加的新型号最相似的现有模型的 YAML 配置文件（例如 `gemini-1.0-pro-001.yaml`）。 - 复制这个 YAML 文件，并将其重命名为能清晰标识新型号的名称（例如 `gemini-1.5-pro-latest.yaml`）。 3. **修改模型配置 (YAML):** - 打开你刚刚重命名的 YAML 文件 (例如 `gemini-1.5-pro-latest.yaml`)。 - **核心步骤：** 参考**模型供应商的官方文档**，仔细核对并修改文件中的以下关键信息： - `model`: **必须**更新为新型号的官方 API 标识符。 - `label`: **必须**更新为在 Dify 界面中展示给用户的模型名称 (建议提供 `en_US` 和 `zh_Hans` 两种语言)。 - `model_properties`: 更新 `context_size` (上下文窗口大小)。 - `parameter_rules`: 检查并更新模型参数的限制，特别是 `max_tokens` (最大输出 Token 数) 的 `default`, `min`, `max` 值。 - `pricing`: 更新模型的输入 (`input`) 和输出 (`output`) 定价，以及单位 (`unit`, 通常是 `0.000001` 表示百万 Token) 和货币 (`currency`)。 - _(参考)_ 关于模型 YAML 文件各字段的详细规范，请查阅 [模型设计规则](/plugin-dev-zh/0411-model-designing-rules) 和 [模型 Schema 定义](/plugin-dev-zh/0412-model-schema)。 **示例 (添加 Gemini 1.5 Pro):** | 参数 | 可能的旧模型 (示例) | 新 Gemini 1.5 Pro (示例) | 说明 | | :---------------- | :------------------- | :----------------------- | :---------------------------------- | | `model` | `gemini-1.0-pro-001` | `gemini-1.5-pro-latest` | **必须**修改为官方模型 ID | | `label: en_US` | Gemini 1.0 Pro | Gemini 1.5 Pro | **必须**修改为用户可见标签 | | `context_size` | 30720 | 1048576 | **必须**根据官方文档修改 | | `max_tokens` (下) | 2048 | 8192 | **必须**根据官方文档修改默认/最大值 | 4. **更新供应商 Manifest 版本:** - 回到该模型供应商的根目录 (例如 `models/vertex_ai/`)。 - 找到并打开 `manifest.yaml` 文件。 - 将其中的 `version` 字段递增一个小版本号 (例如 `version: 0.0.8` -> `version: 0.0.9`)。这告诉 Dify 这是一个更新。 5. **打包与本地测试:** - 打开你的终端 (命令行工具)。 - **确保你的当前目录是 `dify-official-plugins` 仓库的根目录** (即包含 `models`, `tools` 等文件夹的那个目录)。 - 运行打包命令： ```bash # 将 替换为实际的供应商目录名，例如 cohere 或 vertex_ai dify plugin package models/ ``` - _成功后，你会看到类似 `plugin packaged successfully, output path: .difypkg` 的提示，并在当前项目根目录下生成一个名为 `.difypkg` 的插件包文件。_ - 登录你的 Dify 实例 (本地部署或云版本均可)。 - 点击 Dify 页面最顶部导航栏右侧的 **"插件"** 菜单项。 - 在插件页面，点击 **"安装插件"** 按钮。 - 选择 **"本地插件"** 选项卡。 - 点击上传区域，选择或拖拽你刚刚在本地生成的 `.difypkg` 文件进行上传。 - 等待插件安装或更新完成。 - 安装成功后，通常需要前往 "设置" -> "模型供应商" 找到对应的供应商，并配置你的 API 凭证（如果你之前没有配置过的话）。 - 创建一个新的 Dify 应用或编辑现有应用，在 "提示词编排" -> "模型" 设置中，尝试选择你新添加的模型。进行一些简单的对话或调用测试，确保它能正常工作并返回预期结果。 6. **提交你的贡献:** - 本地测试无误后，将你的修改（新的模型 YAML 文件和更新后的 `manifest.yaml`）通过 Git 提交 (commit) 并推送 (push) 到你 Fork 的 GitHub 仓库。 - 在 GitHub 上，向 `langgenius/dify-official-plugins` 主仓库发起一个 Pull Request (PR)。在 PR 描述中，可以简要说明你添加了哪个模型，并附上该模型官方文档的链接，方便审核者确认参数。 --- **然后呢？** 一旦你的 PR 被审核通过并合并，你的贡献就会成为 Dify 官方插件的一部分，所有 Dify 用户都能方便地使用这个新模型了！ 这种快速接入方法是让 Dify 支持新模型的最快途径。当然，如果未来这个模型需要支持更复杂的功能（例如图片输入、函数调用等），那么可能就需要有经验的开发者对插件进行代码层面的更新了。但你现在完成的这一步，已经是非常有价值的贡献！ **探索更多:** - [模型 Schema 定义](/plugin-dev-zh/0412-model-schema) (了解模型 YAML 文件的详细规则) - [模型设计规则](/plugin-dev-zh/0411-model-designing-rules) (了解模型参数设计的规范) - [一般规范定义](/plugin-dev-zh/0411-general-specifications) (了解 `manifest.yaml` 的作用) - [创建新模型提供者](/plugin-dev-zh/0222-creating-new-model-provider) (了解如何添加新的模型提供商) - [发布至 Dify 市场](/plugin-dev-zh/0322-release-to-dify-marketplace) (学习如何发布你的插件) - [Dify 官方插件仓库](https://github.com/langgenius/dify-official-plugins) (查看其他插件的例子) {/* Contributing Section DO NOT edit this section! It will be automatically generated by the script. */} --- [编辑此页面](https://github.com/langgenius/dify-docs/edit/main/plugin-dev-zh/0211-getting-started-new-model.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)