FastGPT 自定义插件开发：从模板到发布全流程-优快云博客

FastGPT 自定义插件开发：从模板到发布全流程

【免费下载链接】FastGPT labring/FastGPT: FastGPT 是一个基于PyTorch实现的快速版GPT（Generative Pretrained Transformer）模型，可能是为了优化训练速度或资源占用而设计的一个实验性项目，适用于自然语言处理任务。项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT

插件开发准备工作

在开始FastGPT插件开发前，需要先了解项目的插件结构。FastGPT的插件系统主要分为模型插件和网页爬虫插件两大类型，所有插件均位于项目的plugins目录下。

官方插件示例：

模型插件：plugins/model
网页爬虫插件：plugins/webcrawler
插件开发文档：plugins/README.md

模型插件是FastGPT最常用的扩展方式，目前已有的模型插件包括LLM模型（如百川2、智谱GLM2）、OCR工具、PDF处理工具等多种类型，完整列表可查看plugins/model目录。

插件目录结构设计

一个标准的FastGPT模型插件需要包含以下核心文件：

plugins/model/[插件名称]/
├── 接口实现.py    # 核心实现文件，遵循标准API规范
└── requirements.txt # 依赖管理文件

以官方的百川2模型插件为例，其目录结构如下：

核心文件说明：

接口实现.py：实现与FastGPT主程序通信的API接口，通常遵循标准API规范
requirements.txt：声明插件运行所需的Python依赖包

开发实战：创建自定义模型插件

1. 初始化插件目录

首先创建插件目录，以"llm-custom"为例：

mkdir -p plugins/model/llm-custom
cd plugins/model/llm-custom
touch 接口实现.py requirements.txt

2. 编写依赖文件

编辑requirements.txt文件，添加插件所需的依赖：

transformers==4.53.0
torch>=2.0
sentencepiece
accelerate
fastapi==0.99.1
uvicorn==0.21.1

依赖版本参考：plugins/model/llm-百川2/requirements.txt

3. 实现核心API逻辑

创建接口实现.py文件，实现插件的核心功能。以下是一个基础模板：

# coding=utf-8
# 自定义LLM插件示例，遵循标准API格式
import torch
import uvicorn
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel, Field, validator
from contextlib import asynccontextmanager
from typing import List, Optional
from transformers import AutoModelForCausalLM, AutoTokenizer

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 初始化模型
    global model, tokenizer
    tokenizer = AutoTokenizer.from_pretrained("你的模型路径", trust_remote_code=True)
    model = AutoModelForCausalLM.from_pretrained("你的模型路径", torch_dtype=torch.float16, trust_remote_code=True).cuda()
    yield
    # 清理资源
    if torch.cuda.is_available():
        torch.cuda.empty_cache()

app = FastAPI(lifespan=lifespan)

# 配置CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 定义请求和响应模型
class ChatMessage(BaseModel):
    role: str
    content: str
    
    @validator('role')
    def check_role(cls, v):
        if v not in ["user", "assistant", "system"]:
            raise ValueError('role must be one of "user", "assistant", "system"')
        return v

class ChatCompletionRequest(BaseModel):
    model: str
    messages: List[ChatMessage]
    stream: Optional[bool] = False

# 实现聊天接口
@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest):
    # 处理请求逻辑
    messages = [{"role": m.role, "content": m.content} for m in request.messages]
    
    # 模型推理
    response = model.chat(tokenizer, messages)
    
    # 返回结果
    return {
        "id": "chatcmpl-123456",
        "object": "chat.completion",
        "created": 1677652288,
        "model": request.model,
        "choices": [{
            "index": 0,
            "message": {"role": "assistant", "content": response},
            "finish_reason": "stop"
        }]
    }

if __name__ == "__main__":
    uvicorn.run(app, host='0.0.0.0', port=6006, workers=1)

完整的实现可参考官方示例：plugins/model/llm-百川2/接口实现.py

插件调试与测试

本地测试插件

开发完成后，可以通过以下命令启动插件服务进行本地测试：

cd plugins/model/llm-custom
pip install -r requirements.txt
python 接口实现.py

服务启动后，插件将在本地6006端口运行，可通过FastAPI自动生成的Swagger文档进行接口测试：

集成到FastGPT主程序

要将开发的插件集成到FastGPT主程序，需要修改主程序的插件配置文件，添加你的插件信息：

{
  "plugins": [
    {
      "name": "llm-custom",
      "type": "model",
      "url": "http://localhost:6006/v1"
    }
  ]
}

插件发布流程

准备发布材料

插件开发完成并测试通过后，准备以下发布材料：

插件功能说明文档（markdown格式）
插件logo图片（建议使用SVG格式）
插件截图（展示主要功能界面）

提交到官方仓库

FastGPT插件的发布流程如下：

Fork官方仓库：https://gitcode.com/GitHub_Trending/fa/FastGPT
将你的插件代码提交到plugins/model/[你的插件名称]目录
修改插件列表文档，添加你的插件信息
创建Pull Request，等待官方审核

提交PR时，请确保你的代码符合项目的代码规范，并提供详细的功能说明和测试报告。官方插件提交界面示例：

高级功能与最佳实践

内存管理优化

在处理大模型时，内存管理尤为重要。可以参考百川2插件中的内存优化策略：

# 显存自动清理逻辑
if torch.cuda.is_available():
    gpu_memory_usage = torch.cuda.memory_allocated() / torch.cuda.max_memory_allocated()
    if gpu_memory_usage > 0.9:
        gc.collect()
        torch.cuda.empty_cache()

完整实现：plugins/model/llm-百川2/接口实现.py#L218-L222

流式响应实现

对于需要长时间处理的任务，建议实现流式响应以提升用户体验：

from sse_starlette.sse import EventSourceResponse

async def generate_stream(messages):
    for chunk in model.chat(tokenizer, messages, stream=True):
        yield {
            "id": "chatcmpl-123",
            "object": "chat.completion.chunk",
            "choices": [{"delta": {"content": chunk}}]
        }

@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest):
    if request.stream:
        return EventSourceResponse(generate_stream(request.messages))
    # 非流式响应处理...

常见问题解决

依赖冲突问题

如果你的插件与其他插件存在依赖冲突，可以使用虚拟环境隔离：

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install -r requirements.txt

模型加载失败

确保模型文件路径正确
检查CUDA环境是否配置正确
验证模型文件完整性

更多插件开发问题可参考官方FAQ：document/content/docs/faq

总结

通过本文介绍的步骤，你已经了解了如何从0开始开发一个FastGPT插件，包括目录结构设计、核心功能实现、本地测试和官方发布的全流程。FastGPT的插件系统设计灵活，支持多种类型的扩展，无论是模型集成、数据处理还是工具调用，都可以通过插件方式实现。

鼓励开发者们积极参与插件生态建设，开发更多实用的插件丰富FastGPT的功能。如有任何开发问题，可通过项目的Issue系统或社区论坛寻求帮助。

最后，附上FastGPT插件开发资源汇总：

插件开发模板：plugins/model
API参考文档：document/content/docs/protocol
官方示例插件：plugins/model/llm-百川2
插件提交指南：plugins/README.md

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考