Guía de inicio rápido de QTEASY

Instalación e importación

Instalar con pip (requiere Python >= 3.9, <3.13): algunas funciones (como todas las estrategias integradas, el almacenamiento en base de datos, etc.) requieren dependencias opcionales; consulta el FAQ y las instrucciones de instalación para más detalles.

pip install qteasy

Tras iniciar, puedes importar qteasy y ver el número de versión:

>>> import qteasy as qt
>>> print(qt.__version__)

La salida es la siguiente:

2.6.0

qteasy historial de versiones: notas de cambio para cada versión, que se pueden ver antes de actualizar.

Puesta en marcha en un minuto

En esta sección te guiaremos para completar: configurar el tushare Token → descargar diez años de datos del índice CSI 300 → revisar los datos y las velas (K) → usar la estrategia DMA integrada para hacer un backtest de timing sobre 000300.SH y obtener un resultado de backtest utilizable.

1. 配置 tushare Token

qteasy usa Tushare de forma predeterminada para descargar datos financieros. Para descargar datos, primero debes configurar el Token de la API de tushare en el archivo de configuración de inicio del sistema (regístrate primero en el sitio oficial de tushare y obtén el Token).

Hay dos formas de modificar el archivo de configuración de inicio:

Método 1: establecer la configuración de inicio en el código Antes de la primera descarga de datos, ejecuta update_start_up_setting() para modificar la configuración de inicio y guardarla automáticamente en el archivo de configuración de inicio:

>>> qt.update_start_up_setting(tushare_token='你的tushare_API_Token')  # 启动配置将被保存到启动配置文件中
>>> qt.start_up_settings()  # 查看启动配置文件的内容

La salida es la siguiente:

Start up settings:
--------------------
tushare_token = <你的tushare_API_token>
...

Método 2: modificar directamente el archivo de configuración de inicio El archivo de configuración de inicio qteasy.cfg se guarda en el directorio raíz de qteasy (puedes ver la ruta del archivo de configuración mediante qt.QT_ROOT_PATH); abre este archivo con cualquier editor de texto y añade una línea:

tushare_token = 你的tushare_API_Token  # 直接打开文件并在其中新增配置，字符串配置不需要使用双引号

2. 下载 000300.SH 十年指数数据

Tras configurar el Token de tushare, descarga los datos diarios del índice CSI 300 (000300.SH). Se recomienda descargar primero el calendario de negociación y la información básica del índice, y luego los datos diarios del índice (aprox. diez años):

Usa la función qteasy.refill_data_source(); qteasy descargará automáticamente los datos desde el canal de descarga configurado. Cuando el volumen de datos sea demasiado grande, descargará automáticamente por bloques, completará la verificación y limpieza de datos y los almacenará en la base de datos.

>>> # 下载交易日历与指数基础信息
>>> qt.refill_data_source(tables=['trade_calendar', 'index_basics'])
>>> # 下载 000300.SH 近十年日线数据
>>> qt.refill_data_source(
...     tables=['index_daily'],
...     start_date='20140101',
...     end_date='20241231',
...     symbols=['000300.SH'],
... )

La salida es la siguiente:

Filling data source file://csv@qt_root/data/ ...
into 1 table(s) (parallely): {'trade_calendar'}
<trade_calendar> 35000 wrn: 100%|█████████████████████████████████████████████████████| 8/8 [00:05<00:00,  1.58task/s]
Data refill completed! 35000 rows written into 1/1 table(s)!

Filling data source file://csv@qt_root/data/ ...
into 2 table(s) (parallely): {'index_daily', 'index_basic'}
<index_daily> 152760 wrn: 100%|███████████████████████████████████████████████████████| 2/2 [00:05<00:00,  2.51s/task]
<index_basic> 1327 wrn: 100%|█████████████████████████████████████████████████████████| 8/8 [00:05<00:00,  1.58task/s]
Data refill completed! 154087 rows written into 2/2 table(s)!

3. 查看数据与 K 线图

Una vez guardados los datos, puedes usar get_history_data para obtenerlos y HistoryPanel.plot y qt.candle para dibujar velas (K), y confirmar si los datos y las cotizaciones son correctos:

>>> # 获取近一年日线，直接返回 HistoryPanel
>>> hp = qt.get_history_data(
...     htypes='open, high, low, close',  # 需要获取的数据类型分别为开盘价、最高价、最低价、收盘价
...     shares='000300.SH',  # 资产类型为沪深300指数
...     start='20230101',  # 数据起始日期
...     end='20231231',  # 数据结束日期
... )
>>> print(hp)  # 查看数据结构与范围
>>> # 在 HistoryPanel 上绘制静态 K 线 + 成交量
>>> hp.plot(interactive=False)
>>> # 或者使用 qt.candle 快速绘制 K 线（内部同样基于 HistoryPanel）
>>> qt.candle('000300.SH', start='2023-06-01', end='2023-12-01', asset_type='IDX')

3.1 Gráficos interactivos (Plotly) y dependencias

Si quieres hacer zoom, desplazarte y ver los valores específicos correspondientes a cada vela K/indicador en el Notebook, puedes usar gráficos interactivos:

>>> hp.plot(interactive=True)

Los gráficos interactivos dependen de Plotly. Se recomienda elegir la instalación según tu entorno de uso:

Interacción básica (Plotly Figure):

pip install plotly

Interacción más completa en Notebook (FigureWidget + callbacks):

pip install ipywidgets anywidget

En Notebook, qteasy intentará priorizar una experiencia más completa con FigureWidget; si el kernel/dependencias actuales no lo permiten, volverá a la visualización en HTML. Si Plotly no está instalado, interactive=True lanzará directamente un mensaje de error en inglés (normalmente contiene “requires plotly”).

3.2 Los parámetros interactivos más usados

plotly_backend_app='auto'|'FigureWidget'|'html': selecciona el modo de salida en el Notebook (por defecto, 'auto').
layout='auto'|'overlay'|'stack': diseño para múltiples activos. 'overlay' se usa más comúnmente solo para superponer y comparar dos activos; 'auto' elegirá automáticamente entre “dos activos → overlay, el resto → stack”.
highlight='max'|'min': resalta los puntos de valor máximo/mínimo (disponible tanto en modo estático como interactivo).

La salida es la siguiente:

{'000300.SH':
               open     high      low    close
2023-01-03  3864.84  3893.99  3831.25  3887.90
2023-01-04  3886.25  3905.90  3873.65  3892.95
2023-01-05  3913.49  3974.88  3912.26  3968.58
...             ...      ...      ...      ...
2023-10-10  3696.25  3701.26  3655.59  3657.13
2023-10-11  3674.75  3689.53  3658.35  3667.55
2023-10-12  3697.93  3711.50  3682.84  3702.38

[186 rows x 4 columns]
}

png

3.5 Operar con datos históricos (HistoryPanel)

En la investigación práctica, muchas veces no solo necesitamos “ver velas (K)”, sino también hacer estadísticas sobre datos históricos en el código y generar factores. get_history_data() además de poder devolver un DataFrame, también puede devolver directamente un HistoryPanel tridimensional, lo que facilita realizar cálculos unificados para múltiples activos y múltiples indicadores:

>>> # 获取 000300.SH 的 OHLCV 历史数据，并返回 HistoryPanel
>>> hp = qt.get_history_data(
...     htypes='open, high, low, close, vol',
...     shares='000300.SH',
...     start='20230101',
...     end='20231231',
...     as_data_frame=False,          # 关键：返回 HistoryPanel
... )
>>> print(hp.shape, hp.shares, hp.htypes)

>>> # 1) 计算简单收益率矩阵（时间 × 股票）
>>> ret = hp.returns(price_htype='close', method='simple')
>>> print(ret.head())

>>> # 2) 计算 20 日滚动波动率
>>> vol = hp.volatility(window=20, price_htype='close', annualize=True)
>>> print(vol.tail())

>>> # 3) 生成 K 线技术指标（如 20 日均线、MACD）
>>> hp_ma = hp.kline.sma(window=20)              # 在 htypes 中新增 'sma_20'
>>> hp_ma_macd = hp_ma.kline.macd()              # 再追加 MACD 指标
>>> print(hp_ma_macd.htypes)

>>> # 4) 识别蜡烛形态（如锤头线）
>>> hammer = hp.candle_pattern('cdlhammer')      # 返回 DataFrame，非 0 代表出现形态
>>> print(hammer[hammer['000300.SH'] != 0].head())

>>> # 5) 单只股票切片成 DataFrame，方便与 pandas / sklearn 等联动
>>> df_300 = hp_ma_macd.to_share_frame('000300.SH')
>>> print(df_300.tail())

El ejemplo anterior muestra cómo, tras obtener un HistoryPanel desde get_history_data(..., as_data_frame=False), se pueden calcular en una o dos líneas de código rentabilidad, volatilidad, indicadores técnicos y señales de patrones, y volver en cualquier momento al conocido DataFrame para un análisis más profundo.

Para un uso más sistemático de HistoryPanel, puedes consultar el capítulo “Operación y análisis de datos históricos” en el «Tutorial de uso», así como la referencia de la API de HistoryPanel.

4. 使用 DMA 策略做择时回测

Utiliza la estrategia integrada de timing con medias móviles DMA, tomando 000300.SH como activo de trading, y realiza un backtest sobre diez años de datos ya descargados. A continuación se usa un conjunto de parámetros comunes y relativamente estables (media corta 20, media larga 60, periodo DMA 10) para obtener directamente los resultados y gráficos del backtest:

>>> # 设置qteasy的运行配置参数
>>> qt.configure(
...     asset_pool='000300.SH',  # 交易资产池包括沪深300指数
...     asset_type='IDX',  # 投资资产类型为IDX-指数
...     invest_cash_amounts=[100000],  # 回测初始投资金额为十万元
...     invest_start='20150101',  # 回测投资初始日期
...     invest_end='20241231',  # 回测投资结束日期
...     cost_rate_buy=0.0003,  # 交易费率：买入手续费万分之三
...     cost_rate_sell=0.0001,  # 交易费率：卖出手续费万分之一
...     visual=True,  # 是否输出回测结果可视化图表：是
...     trade_log=True,  # 是否输出回测记录：是
... )
>>> op = qt.Operator(strategies='dma')  # 创建一个交易员对象，执行一个DMA交易策略
>>> op.set_parameter('dma', par_values=(20, 60, 10))  # 设置交易策略的参数
>>> res = qt.run(op, mode=1)  # 启动交易，运行模式为1（回测交易）

La salida es la siguiente:

====================================
|                                  |
|         BACKTEST REPORT          |
|                                  |
====================================
qteasy running mode: 1 - History back testing
time consumption for operate signal creation: 81.3 ms
time consumption for operation back testing:  4.9 ms
investment starts on      2015-01-05 15:00:00
ends on                   2024-12-30 15:00:00
Total looped periods:     10.0 years.
-------------operation summary:------------
Only non-empty shares are displayed, call 
"loop_result["oper_count"]" for complete operation summary
          Sell Cnt Buy Cnt Total Long pct Short pct Empty pct
000300.SH   340       41    381   44.7%     -0.0%     55.3%  

Total operation fee:     ¥    3,261.19
total investment amount: ¥  100,000.00
final value:              ¥  115,601.73
Total return:                    15.60% 
Avg Yearly return:                1.46%
Skewness:                         -1.16
Kurtosis:                         16.95
Benchmark return:                 1.67% 
Benchmark Yearly return:          0.17%

------strategy loop_results indicators------ 
alpha:                            0.006
Beta:                             0.975
Sharp ratio:                      0.113
Info ratio:                       0.001
250 day volatility:               0.130
Max drawdown:                    36.85% 
    peak / valley:        2015-04-27 / 2018-11-27
    recovered on:         Not recovered!


==================END OF REPORT===================

png

Tras ejecutarlo, se obtendrán la curva de rendimiento, el máximo drawdown, el ratio de Sharpe y otros indicadores de evaluación, además de gráficos de visualización. Si quieres probar otros parámetros u optimizar rangos, consulta la siguiente sección «qué puede hacer qteasy» sobre optimización de parámetros y la documentación de backtesting.

Qué puede hacer `qteasy`

Obtener y gestionar datos históricos financieros:

Obtener cómodamente grandes volúmenes de datos históricos financieros desde múltiples canales y, tras la limpieza de datos, almacenarlos localmente en un formato unificado
Mediante el objeto DataType se gestiona de forma estructurada la información disponible en los datos financieros; incluso información compleja como precios ajustados o componentes de un índice puede obtenerse con una sola línea de código
Visualización de datos financieros, análisis estadístico y visualización de resultados de análisis basados en el objeto DataType
Almacenamiento local de datos y acceso bajo demanda, proporcionando una base de datos coherente para backtesting y trading en vivo, lo que facilita la reproducibilidad

png

Crear estrategias de trading de forma sencilla y segura

A través de la clase BaseStrategy, los métodos para definir estrategias de trading son intuitivos y la lógica es clara
Más de 70 estrategias integradas listas para usar; un mecanismo único de mezcla y combinación de estrategias permite ensamblar estrategias complejas a partir de estrategias simples, como si se construyera con bloques
La entrada de datos y el modo de uso de la estrategia de trading están completamente encapsulados y son seguros, evitando por completo problemas como el uso involuntario de funciones futuras y la fuga de datos, y garantizando la autenticidad y fiabilidad de los resultados de ejecución de la estrategia
La misma lógica de estrategia se usa tanto para backtesting como para trading en vivo, reduciendo la brecha de «backtest bonito, en vivo se desvirtúa»

png

Evaluación, optimización y simulación de trading automatizado de estrategias de trading

Gestiona la ejecución de la estrategia mediante la clase de trader Operator, realiza backtesting siguiendo el ritmo real de negociación del mercado, evalúa los resultados de trading de forma integral y multidimensional, y genera informes de trading y gráficos de resultados
Ofrece diversos algoritmos de optimización, incluidos recocido simulado, algoritmos genéticos, optimización bayesiana, etc., para optimizar el rendimiento de la estrategia en espacios de parámetros grandes
Obtén datos de mercado en tiempo real, ejecuta estrategias para simular trading automatizado y realiza el seguimiento y registro de información como el registro de operaciones, las posiciones de acciones y los cambios en los fondos de la cuenta
El backtesting, la optimización y el trading en vivo utilizan el mismo mecanismo de ejecución: escribe la estrategia una sola vez y ejecútala en todos los modos. La configuración es clara y facilita la reproducción y la depuración
En el futuro, se conectará a la interfaz de trading en vivo proporcionada por el bróker a través de la interfaz QMT para habilitar el trading automatizado

png
png
png

Hoja de ruta / tutorial de extremo a extremo

Si desea seguir el flujo completo «desde la configuración hasta el backtesting, la optimización y la simulación/operación en real», puede leer los tutoriales y la documentación en el siguiente orden; cada paso cuenta con su capítulo y ejemplos correspondientes:

Configurar la fuente de datos y el token → Tutorial: Primeros pasos, Tutorial: Obtener datos
Descargar datos → Tutorial: Obtener datos, Descargar y gestionar datos históricos financieros
Definir una estrategia y hacer backtesting → Tutorial: primera estrategia、Tutorial: estrategias integradas、Tutorial: estrategia personalizada、Cómo ejecutar un backtest
Optimización de parámetros → Tutorial: optimización de estrategias de trading、Optimizar estrategias de trading
Ejecución en simulación/real → Tutorial: despliegue y ejecución de estrategias de trading、Resumen de ejecución simulada/en real

Los tutoriales anteriores ya cubren la cadena completa desde la configuración hasta el backtesting, la optimización y la simulación/operación en real; si encuentra problemas, puede consultar en el FAQ explicaciones comunes como «cómo completar el flujo», «por qué es lento», «evitar funciones del futuro», etc.

A continuación

Tutorial: obtener datos — Configurar la fuente de datos y descargar más datos
Tutorial: primera estrategia — Usar estrategias integradas y hacer backtesting
Backtesting y evaluación — Parámetros de backtesting e interpretación de resultados
Referencia de la API — Descripción completa de la interfaz

Guía de inicio rápido de QTEASY

Instalación e importación

Puesta en marcha en un minuto

1. 配置 tushare Token

2. 下载 000300.SH 十年指数数据

3. 查看数据与 K 线图

3.1 Gráficos interactivos (Plotly) y dependencias

3.2 Los parámetros interactivos más usados

3.5 Operar con datos históricos (HistoryPanel)

4. 使用 DMA 策略做择时回测

Qué puede hacer qteasy

Obtener y gestionar datos históricos financieros:

Crear estrategias de trading de forma sencilla y segura

Evaluación, optimización y simulación de trading automatizado de estrategias de trading

Hoja de ruta / tutorial de extremo a extremo

A continuación

Qué puede hacer `qteasy`