15. 自定义插件开发

15.自定义插件开发

本文将详细介绍如何在 Freqtrade 中开发自定义插件,包括插件的基本结构、钩子函数的使用方法、功能扩展技巧以及插件分享的最佳实践。通过本章的学习,我们将能够根据自己的交易需求,开发出符合个人策略的插件,从而增强 Freqtrade 的功能。

插件结构

Freqtrade 的插件系统设计灵活,允许开发者通过继承特定的基类来实现自定义功能。所有插件都需要遵循一定的结构规范,以确保能够被系统正确加载和运行。

基类继承

在开发插件时,首先需要选择合适的基类。对于 Pairlist 插件,需要继承 IPairList 类;对于 Protections 插件,则需要继承 IProtection 类。这些基类定义了插件必须实现的方法,确保插件能够与 Freqtrade 核心系统无缝集成。

以下是一个 Pairlist 插件的基本结构示例:

from freqtrade.plugins.pairlist.IPairList import IPairList
from typing import List, Dict

class CustomPairList(IPairList):
    def __init__(self, exchange, pairlistmanager, config, pairlistconfig, pairlist_pos):
        super().__init__(exchange, pairlistmanager, config, pairlistconfig, pairlist_pos)
        # 初始化插件参数
        self._number_assets = self._pairlistconfig.get('number_assets', 20)

    @property
    def needstickers(self) -> bool:
        # 是否需要 ticker 数据
        return True

    def short_desc(self) -> str:
        # 插件简短描述
        return f"CustomPairList - top {self._number_assets} pairs"

    def gen_pairlist(self, tickers: Dict) -> List[str]:
        # 生成初始交易对列表
        pairs = self._exchange.get_markets().keys()
        # 自定义筛选逻辑
        filtered_pairs = self._filter_pairs(pairs, tickers)
        return filtered_pairs[:self._number_assets]

    def _filter_pairs(self, pairs: List[str], tickers: Dict) -> List[str]:
        # 实现自定义筛选逻辑
        filtered = []
        for pair in pairs:
            # 例如:筛选出价格大于 0.001 的交易对
            if tickers[pair]['last'] > 0.001:
                filtered.append(pair)
        return filtered

配置参数

插件的配置参数需要在构造函数中进行初始化,并可以通过配置文件进行自定义。建议使用 _pairlistconfig 或 _config 来获取用户配置的参数,以保持与 Freqtrade 配置系统的一致性。

例如,在上述示例中,number_assets 参数通过 self._pairlistconfig.get('number_assets', 20) 获取,允许用户在配置文件中自定义该值。

钩子函数

钩子函数是插件与 Freqtrade 核心系统交互的关键。通过重写基类中的钩子函数,插件可以在特定事件发生时执行自定义逻辑。

Pairlist 插件钩子

对于 Pairlist 插件,主要的钩子函数包括:

  • gen_pairlist(tickers: Dict) -> List[str]: 生成初始交易对列表,当插件作为链中的第一个处理器时调用。
  • filter_pairlist(pairlist: List[str], tickers: Dict) -> List[str]: 过滤交易对列表,当插件作为链中的后续处理器时调用。

以下是 filter_pairlist 方法的实现示例,用于根据交易量过滤交易对:

def filter_pairlist(self, pairlist: List[str], tickers: Dict) -> List[str]:
    # 按交易量排序并筛选
    sorted_pairs = sorted(pairlist, key=lambda x: tickers[x]['quoteVolume'], reverse=True)
    return sorted_pairs[:self._number_assets]

Protections 插件钩子

对于 Protections 插件,主要的钩子函数包括:

  • global_stop(date_now: datetime) -> ProtectionReturn: 全局停止交易检查,返回是否需要停止所有交易对的交易。
  • stop_per_pair(pair: str, date_now: datetime) -> ProtectionReturn: 单交易对停止检查,返回是否需要停止特定交易对的交易。

以下是 stop_per_pair 方法的实现示例,用于实现交易对的冷却期保护:

from freqtrade.plugins.protections.IProtection import IProtection, ProtectionReturn
from datetime import datetime, timedelta

class CustomCooldownProtection(IProtection):
    def __init__(self, config, protection_config):
        super().__init__(config, protection_config)
        self._stop_duration = self._protection_config.get('stop_duration_candles', 2)

    def short_desc(self) -> str:
        return f"CustomCooldownProtection - {self._stop_duration} candles"

    def stop_per_pair(self, pair: str, date_now: datetime) -> ProtectionReturn:
        # 获取该交易对的最近交易
        trades = self._db.get_trades(pair=pair, limit=1)
        if trades:
            last_trade = trades[0]
            # 计算冷却期结束时间
            lock_end = last_trade.close_date + timedelta(minutes=self._stop_duration * self._config['timeframe_minutes'])
            if date_now < lock_end:
                return ProtectionReturn(True, lock_end, f"Cooldown period active until {lock_end}")
        return ProtectionReturn(False, None, "")

功能扩展

除了基本的插件结构和钩子函数,还可以通过以下方式扩展插件的功能:

注册插件

开发完成的插件需要注册到 Freqtrade 系统中,才能在配置文件中使用。对于 Pairlist 插件,需要将其添加到 constants.py 文件的 AVAILABLE_PAIRLISTS 列表中:

# freqtrade/constants.py
AVAILABLE_PAIRLISTS = {
    # ...
    'CustomPairList': 'freqtrade.plugins.pairlist.CustomPairList',
    # ...
}

使用缓存

为了提高性能,对于计算密集型或网络请求频繁的插件,可以实现缓存机制。例如,在 gen_pairlist 方法中,可以检查缓存是否过期,避免重复计算:

def gen_pairlist(self, tickers: Dict) -> List[str]:
    if self._cached_pairlist and not self._is_cache_expired():
        return self._cached_pairlist
    # 生成新的交易对列表
    self._cached_pairlist = self._calculate_pairlist(tickers)
    self._cache_expiry = datetime.now() + timedelta(seconds=self._refresh_period)
    return self._cached_pairlist

集成外部数据

插件可以集成外部数据源来增强功能。例如,从外部 API 获取市场情绪数据,用于交易对筛选:

import requests

def _get_market_sentiment(self, pair: str) -> float:
    # 调用外部 API 获取情绪分数
    response = requests.get(f"https://api.example.com/sentiment/{pair}")
    return response.json().get('score', 0.5)

def _filter_pairs(self, pairs: List[str], tickers: Dict) -> List[str]:
    filtered = []
    for pair in pairs:
        sentiment = self._get_market_sentiment(pair)
        if sentiment > 0.7:
            filtered.append(pair)
    return filtered

插件分享

开发完成的插件可以分享给其他 Freqtrade 用户,以下是一些分享的最佳实践:

文档编写

为插件编写清晰的文档,包括:

  • 插件功能描述
  • 配置参数说明
  • 使用示例
  • 依赖项列表

例如:

# CustomPairList 插件

## 功能
根据市场情绪和交易量筛选交易对。

## 配置参数
- `number_assets`: 保留的交易对数量,默认 20
- `sentiment_threshold`: 情绪分数阈值,默认 0.7

## 使用示例

"pairlists": [
    {
        "method": "CustomPairList",
        "number_assets": 15,
        "sentiment_threshold": 0.6
    }
]

代码规范

遵循 Freqtrade 的代码规范,包括:

  • 使用类型注解
  • 编写单元测试
  • 遵循 PEP 8 编码规范

例如,为插件编写单元测试:

# tests/plugins/test_custom_pairlist.py
import pytest
from freqtrade.plugins.pairlist.CustomPairList import CustomPairList

def test_gen_pairlist(mocker):
    # 模拟交易所和 ticker 数据
    exchange = mocker.Mock()
    exchange.get_markets.return_value = {'BTC/USDT': {}, 'ETH/USDT': {}}
    tickers = {
        'BTC/USDT': {'last': 0.002, 'quoteVolume': 1000},
        'ETH/USDT': {'last': 0.0015, 'quoteVolume': 800}
    }
    # 初始化插件
    pairlist = CustomPairList(exchange, None, {}, {'number_assets': 1}, 0)
    # 测试生成交易对列表
    result = pairlist.gen_pairlist(tickers)
    assert len(result) == 1
    assert result[0] == 'BTC/USDT'

社区贡献

如果插件具有通用性,可以考虑通过 Pull Request 将其贡献给 Freqtrade 官方代码库。在提交之前,确保:

  • 插件功能符合 Freqtrade 的设计理念
  • 代码经过充分测试
  • 文档完整且易于理解

通过社区贡献,不仅可以帮助其他用户,还能获得来自 Freqtrade 开发团队的反馈和改进建议。

总结

自定义插件开发是扩展 Freqtrade 功能的强大方式。通过继承适当的基类、实现钩子函数、合理配置参数,以及遵循最佳实践,我们可以开发出高效、可靠的插件。无论是用于交易对筛选、风险保护,还是集成外部数据,插件都能为我们的量化交易策略提供更多可能性。希望本章的内容能够帮助我们顺利开发出自己的第一个 Freqtrade 插件,并在社区中分享我们的成果。