dify-docs/plugin-dev-zh/0211-getting-started-new-model.mdx

---
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
    # 将 <provider_name> 替换为实际的供应商目录名，例如 cohere 或 vertex_ai
    dify plugin package models/<provider_name>
    ```

    - _成功后，你会看到类似 `plugin packaged successfully, output path: <provider_name>.difypkg` 的提示，并在当前项目根目录下生成一个名为 `<provider_name>.difypkg` 的插件包文件。_
    - 登录你的 Dify 实例 (本地部署或云版本均可)。
    - 点击 Dify 页面最顶部导航栏右侧的 **"插件"** 菜单项。
    - 在插件页面，点击 **"安装插件"** 按钮。
    - 选择 **"本地插件"** 选项卡。
    - 点击上传区域，选择或拖拽你刚刚在本地生成的 `<provider_name>.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)