Qbot xalpha 快速开始：基金数据获取、交易模拟、组合管理与策略回测实战指南-平芜编程栈

Qbot xalpha 快速开始：基金数据获取、交易模拟、组合管理与策略回测实战指南

【免费下载链接】Qbot[🔥updating ...] AI 自动量化交易机器人(完全本地部署) AI-powered Quantitative Investment Research Platform. 📃 online docs: https://ufund-me.github.io/Qbot ✨ :news: qbot-mini: https://github.com/Charmve/iQuant项目地址: https://gitcode.com/GitHub_Trending/qbot/Qbot

本文以 Qbot 仓库中pyfunds/backtest子项目内嵌的 xalpha 库（版本 0.11.7）的官方快速开始文档为主体，系统讲解如何一行代码获取场外基金与指数信息、如何用最简账单精确模拟基金交易行为、如何汇总分析多基金投资组合，以及如何用策略类生成定投/网格交易账单进行回测。读完后你将能够独立跑通「数据获取 → 单标的交易分析 → 组合管理 → 策略回测 → 通用行情获取」的完整量化研究链路。

一、模块定位与入口

xalpha 是 Qbot 仓库pyfunds/backtest目录下的核心分析库，官方定位是：对场外基金和指数进行方便的追踪和研究，实现投资情况的汇总管理与数据分析，并支持简单的基金购买策略回测。快速开始文档只覆盖了最小可用面，更完整的函数与可视化用法可参考 demo.rst 中的 Notebook 示例，数据结构与模块设计则参见 advance.rst。

从 xalpha/init.py 的导出可以确认该模块对外暴露的核心 API 面：

信息类：fundinfo、indexinfo、cashinfo、mfundinfo、FundReport、get_fund_holdings；
账单与交易：record/irecord、trade/itrade；
组合管理：mul、mulfix、imul；
策略：xalpha.policy子模块（buyandhold、scheduled等）；
实时提醒：realtime.review；
通用数据获取器：get_daily、get_rt、get_bar、vinfo；
估值与工具：PEBHistory、QDIIPredict、CBCalculator（可转债估值）等。

安装与本地阅读文档的方式：pip install xalpha（官方包）；仓库内版本可直接使用源码，依赖见 requirements.txt，打包配置见 setup.py。文档可用 Sphinx 在本地构建（cd doc && make html），源码入口见 doc/source/index.rst。

二、基金和指数的信息获取

2.1 场外基金：fundinfo

使用xalpha.info.fundinfo获取场外基金的基本信息和历史每日净值，净值以pandas.DataFrame格式存储。

重要限制：fundinfo只支持按净值法结算的场外基金，货币基金不被支持，货币基金需额外使用xalpha.info.mfundinfo类。

代码示例（继承自官方文档）：

>>> import xalpha as xa >>> zzyl = xa.fundinfo('000968') >>> zzyl 广发养老指数A >>> zzyl.info() fund name: 广发养老指数A fund code: 000968 fund purchase fee: 0.12% fund redemption fee info: ['小于7天', '1.50%', '大于等于7天，小于1年', '0.50%', '大于等于1年，小于2年', '0.30%', '大于等于2年', '0.00%'] >>> zzyl.price[zzyl.price['date']<='2015-02-27'] comment date netvalue totvalue 0 2015-02-13 1.0000 1.0000 1 2015-02-17 1.0000 1.0000 2 2015-02-27 1.0123 1.0123

info()输出中包含申购费与各持有区间的赎回费，这些费率数据是后续交易模拟精确计费的输入。price表中netvalue为单位净值、totvalue为累计净值，comment列用于记录分红/拆分等事件。

底层实现上，price表的comment列由 info.py 中的_nfloat函数解析：分红、现金分红折算为正值，拆分/分拆折算为负值，无法识别的原始文本则原样保留并告警，保证净值序列与分红送转事件一一对应。

2.2 基金持仓穿透

fundinfo对象还提供了持仓明细接口。示例（继承自官方文档）：

>>> zzyl.get_stock_holdings(2019, 4) code name ratio share value 0 300773 拉卡拉 1.48 32.31 2535.37 1 600053 九鼎投资 1.44 97.15 2470.51 2 002624 完美世界 1.32 51.38 2268.08 ... 91 002973 侨银环保 0.00 0.11 0.66 >>> zzyl.get_bond_holdings(2019, 4) # 无债券持仓时返回 None

对应源码 get_fund_holdings 的签名说明了取值规则：season取 1~4，内部换算为month = 3 * season；category支持"stock"/"jjcc"与"bond"/"zqcc"两套等价写法，未识别的类别会抛出ParserFailure；对应期间无持仓时返回None而非报错。从源码结构看，数据抓取自天天基金 F10 接口并按季度归档，因此能覆盖全部持仓而不止十大权重。

2.3 指数信息：indexinfo

使用xalpha.info.indexinfo获取指数的每日净值。代码示例（继承自官方文档）：

>>> zzyli = xa.indexinfo('SZ399812') >>> zzyli 养老产业 >>> zzyli.price[zzyli.price['date']=='2018-08-01'] comment date netvalue totvalue 1 2018-08-01 7.603842 7524.4807

两个关键约定（官方 note）：

指数代码为 7 位：后六位是正常指数代码，第一位标记市场——0是沪市，1是深市；也可以直接使用SH/SZ加 6 位代码的形式（如SZ399812）。
双值列含义：price表中netvalue为以初始日归一化后的净值，totvalue才是真实的指数点位值。做归一化对比分析用前者，还原真实点位用后者。

三、单一标的交易处理

使用xalpha.trade.trade处理交易情况。为了生成交易，需要提供标的类（xalpha.info的实例）和交易账单 status table。代码示例（继承自官方文档）：

>>> yyws = xa.fundinfo('001180') # 交易标的信息 >>> statb = xa.record(path).status # path 位置的交易账单 csv >>> yyws_t = xa.trade(yyws, statb) >>> yyws_t.dailyreport() {'currentshare': 630.39, 'currentvalue': 504.12, 'date': datetime.datetime(2018, 8, 5, 0, 0), 'originalvalue': 523.86, 'returnrate': -3.7682, 'unitcost': 0.831, 'unitvalue': 0.79969999999999997} >>> yyws_t.xirrrate('2018-08-01') -0.01764033506484772

dailyreport()输出当前份额、现值、成本、收益率与单位成本/单位净值；xirrrate(date)输出截至指定日期的年化 IRR 收益率，是评估资金反复进出型账户的核心指标。

3.1 status 账单的数据结构（源码级解读）

账单是整个 xalpha 体系的输入原语，其编码规则在 record.py 的类文档字符串中有完整定义，这里必须掌握：

基本格式：record读取 csv 账单，第一行为date加各基金代码，每行一个交易日期（形如20170129）。不同列代表不同基金，不同行代表不同日期。无交易可留空或填 0；申购为正数（对应申购金额，扣费前状态），赎回为负数（对应赎回份额）——恰好对应基金「金额申购、份额赎回」原则。记录精度只完美支持一位小数。

特殊标记（利用小数位编码语义）：

标记位置	规则	含义
小数点后第 2 位为 5	当日恰好是该基金分红日	标记「分红再投入」，否则默认分红拿现金（该默认行为可反转）
赎回负数绝对值 < 0.005	如`-0.001`	标记赎回份额占总份额的比例而非份额数目，`-0.005`对应全部赎回，线性类推（`0.001`即赎回 20%）
小数点后第 3 位为 5	如`-51.28515`、`200.205`	该笔交易的费用为自定义值：标记位 5 之后代表 1% 位，`-51.28515`表示赎回 51.28 份且赎回费为 1.5%；`200.205`表示申购 200.2 元且申购费为 0

基金性质位 property（0-7 数字）：三个 0/1 开关相加得到 0-7 的十进制编码，类似 Unix 文件权限位——份额四舍五入（0）还是全部舍弃（1）、默认现金分红（0）还是分红再投（2）、赎回对应份额（0）还是金额（4，只支持货币基金）。该数字可写在记账单基金代码行头的下一行（配合record(path, fund_property=True)），或直接在账单第二行日期栏写property（record.py 中检测到df.iloc[0]["date"] == "property"即自动启用），也可在mul初始化时以字典传入。

两种账单形态：默认format="matrix"的矩阵式记账单；format="list"为流水单，共三列date/fund/trade，日期形式为%Y/%m/%d（与 matrix 不含/相区分），读取后会自动透视聚合为 matrix 形式（见 record.py 的实现）。

仓库测试目录提供了多种真实账单样例供对照，包括 demo.csv、demo1.csv 等，相关解析逻辑由 test_trade.py 与 test_universal.py 等测试覆盖。

四、基金投资组合的管理分析

使用xalpha.multiple.mul可以将多个基金交易类归总，或者根据 status 表格上记录的基金代码自动汇总。如果选择xalpha.multiple.mulfix归总交易情况，则所有交易视作封闭系统，资金进出由虚拟的货币基金调节——这正是「总金额固定」的回测口径。

代码示例（继承自官方文档）：

>>> invclose = xa.mulfix(yyws_t, totmoney=6000) >>> invclose.combsummary() 基金代码 基金名称 基金成本 基金收益率 基金现值 0 001180 广发医药卫生联接A 523.86 -3.7682 504.12 1 mf 货币基金 5476.15 7.3475 5878.51 2 xxxxxx 总计 6000.01 6.3770 6382.63 >>> invopen = xa.mul(status=xa.record(path).status) >>> invopen.combsummary('2018-07-01').iloc[-1] 基金代码 xxxxxx 基金名称 总计 基金成本 2379.52 基金收益率 -4.2559 基金现值 2278.25 Name: 5, dtype: object >>> invopen.xirrrate('2018-07-01') -0.05594572489624858

注意mulfix结果中虚拟货币基金行代号为mf，末行xxxxxx为总计行；combsummary(date)还支持指定日期做截面汇总，组合级的xirrrate同样给出年化 IRR。

从源码看 multiple.py 中mul类的构造：传入status时，会自动遍历账单列中的每个基金代码，按 property 位解析出round_label/dividend_label/value_label并逐一构建trade(fundinfo(code, ...))实例，因此只要账单里出现过的基金，无需手动逐个构造交易对象；还支持fetch/save（本地文件缓存 IO）与path传 SQLAlchemy engine、form="sql"的数据库持久化，实现 csv 与数据库 IO 的无缝切换。combsummary等聚合方法内部复用 trade.py 中的xirrcal、vtradecost等量化函数。

五、基金交易策略与回测

通过额外导入policy模块，使用xalpha.policy.policy的子类，可以按一定策略生成模拟交易的 status 表格，从而进行交易分析，起到策略回测比较的作用。策略类对应实例的self.status属性即为该策略生成的 status 交易表格，可直接送入上一节的trade/mul体系做分析。

代码示例（继承自官方文档）：

>>> st = xa.policy.buyandhold(yyws, '2016-01-01') # buy and hold from 2016-01-01, 且始终分红再投入 >>> st2 = xa.policy.scheduled(yyws, totmoney=1000, times=pd.date_range('2016-01-01', '2018-06-01', freq='W-THU')) # 定投 status 的生成：从 2016-01-01 到 2018-06-01 每周四进行定额定投 1000 元。

对应源码 policy.py 中，policy基类继承自record（第 11 行），buyandhold（第 59 行）与scheduled（第 77 行）是文档点名的两个现成策略：前者生成「买入并持有 + 分红再投入」账单，后者按给定日期序列（pd.date_range的任意频率）逐笔生成定额申购账单——由于账单本身支持变额，变额定投与网格策略同样可以在此框架下用一行完成。

六、交易策略的监视和定时提醒

使用xalpha.realtime.review可以实现策略的监测和邮件发送，即按自定义策略生成提醒脚本，实现按计划买入和对市场的实时监控，尤其适合复杂网格策略的执行——不需要自己再去看盘和计算执行条件与金额。review从 realtime.py 导出并已在包初始化时挂载；具体用法可参考仓库文档示例目录 doc/samples 中的 Notebook，以及 demo.rst 列出的示例索引。

七、通用日线和实时数据获取器

这是 xalpha 覆盖面最广的子系统，由 universal.py 实现，三个函数均以「代码」为唯一入参，直接返回 DataFrame/json：

xalpha.universal.get_daily：给定代码返回日线 DataFrame。覆盖沪深市场的股票、基金、ETF、LOF、可转债债券；香港市场的股票与指数；美国市场的股票、指数、ETF；人民币兑外币中间价；以及其他在 investing.com 上可访问的金融产品的日线数据。还包括可从标普、FT 和彭博网站找到的标的数据，以及以聚宽为数据源的指数估值数据、基金份额数据、指数总盈利/总资产数据和宏观经济数据。
xalpha.universal.get_rt：给定代码返回实时数据 json。覆盖沪深市场的股票、场内基金、ETF、LOF、可转债债券；港股、美股市场的股票、指数、ETF；及其他 investing.com 标的。
xalpha.universal.get_bar：给定代码返回相应标的的分钟线、5 分钟线、小时线、周线等不同频率的近期分时数据。

代码示例（继承自官方文档，含多种市场的数据形态）：

>>> xa.get_daily("EUR/CNY", prev=5) # 人民币中间价数据 date close 4 2020-03-30 7.8288 3 2020-03-31 7.8088 2 2020-04-01 7.8090 1 2020-04-02 7.7678 0 2020-04-03 7.7081 >>> xa.get_daily("currencies/usd-cnh") # 英为离岸人民币 date open close high low percent 260 2019-04-05 6.7167 6.7122 6.7194 6.7033 -0.07% ... 3 2020-03-31 7.1133 7.0940 7.1177 7.0796 -0.29% 2 2020-04-01 7.0932 7.1230 7.1336 7.0772 0.41% 1 2020-04-02 7.1216 7.0929 7.1422 7.0846 -0.42% 0 2020-04-03 7.0919 7.1108 7.1197 7.0857 0.25% >>> xa.get_daily("FT-ZGLD:SWX:CHF", start="2020-03-01") # ft.com 基金数据 date open close high low 24 2020-03-02 470.10 465.30 472.05 463.75 ... 3 2020-03-31 475.70 474.00 475.70 469.80 2 2020-04-01 466.90 468.10 470.80 464.10 1 2020-04-02 468.45 476.75 479.80 467.40 0 2020-04-03 477.80 481.00 483.00 477.55 >>> xa.get_daily("HK00700", prev=5, end="2018-08-08") # 雪球港股数据 date open close high low percent 198 2018-08-03 347.2475 348.8432 353.6300 345.6519 1.39 ... 201 2018-08-08 365.5972 363.0043 365.5972 359.6136 1.96 >>> xa.get_daily("SH000050", prev=10) # 雪球A股指数数据 date open close high low percent 3 2020-03-25 2203.7900 2206.63 2216.0700 2188.3800 2.41 ... 10 2020-04-03 2197.7113 2195.55 2210.2124 2188.8462 -0.41

分钟/小时线（get_bar）示例：

>>> xa.get_bar("LK", interval=3600, prev=12) # 雪球美股小时线数据 date open high low close volume turnoverrate percent 0 2020-04-03 00:30:00 7.3001 7.60 6.71 7.0497 30253047 12.58 -3.23 ... 11 2020-04-04 03:30:00 5.6300 5.84 5.54 5.6550 5066923 2.01 0.53 >>> xa.get_bar("commodities/brent-oil", interval=60) # 英为油价分钟线 date close 0 2020-04-04 04:36:00 34.87 ... 23 2020-04-04 04:59:00 34.83

实时数据（get_rt）示例：

>>> xa.get_rt("SH501018") # 实时行情数据 {'name': '南方原油LOF', 'current': 0.826, 'percent': -0.48, 'current_ext': None, 'currency': 'CNY', 'market': 'CN'} >>> xa.get_rt("indices/germany-30") # 海外指数实时数据 {'name': '德国DAX30指数 (GDAXI)', 'current': 9525.77, 'current_ext': None, 'currency': 'EUR', 'percent': -0.47, 'market': 'DE'}

7.1 vinfo：任何日线标的都能「套壳」为 info 类

更有趣的是，任何get_daily可获取的标的，都可以用vinfo套壳成第二节介绍的 info 类，从而进行模拟交易和组合分析——不管其底层是原油、汇率甚至是 AH 比价。代码示例（继承自官方文档）：

>>> oil = xa.vinfo("commodities/brent-oil", start="20180101") >>> oil.info() fund name: 伦敦布伦特原油期货 - 2020年6月 (LCOM0) fund code: commodities/brent-oil fund purchase fee: 0% # 如上的 oil info 对象也可以进行 trade 交易和 mul 组合分析 >>> oil.max_drawdown() (Timestamp('2018-10-03 00:00:00'), Timestamp('2020-03-31 00:00:00'), -0.736470042878665)

这体现了 xalpha 的范式统一性：info → trade → mul → policy的分析链路对基金、指数和任意通用行情标的完全一致，vinfo/VInfo从 universal.py 导出，并经init.py 挂载到包顶层，因此写作xa.vinfo即可调用。

八、功能综述

鉴于快速开始只涵盖极小一部分功能，官方文档同时整理了 xalpha 模块的完整功能清单（共 21 项，继承自原文档）：

全部基金（包括货币基金）的信息获取：指定一个代码，就能了解基金名称、历史单位净值、历史分红送转情况、折扣申购费、不同持仓时长的赎回费等多样的信息。
全部 A 股指数的信息获取：同样是一个代码，获取指数名称和每日净值。
所有基金指数数据支持增量更新，csv 文件和数据库 io 的无缝支持。
可以对多只基金和指数同时进行量化分析，给出走势分布和相关性分析。
虚拟可调的货币基金类型：除了前述的真实货币基金类外，还可以建立虚拟的货币基金类，来模拟理财等的行为，或单纯作为量化的基准，实现更灵活的仓位管理。
只需最简的账单外加一个代码，就可以精确模拟一只基金用户的全部交易行为，并输出各种量化数据和可视化。
大量基于回测的量化数据和基于趋势交易的技术面指标工具箱。
只需一个最简的账单，就可实现多基金投资系统的投资精确模拟，同时提供总金额固定和总金额变动两个选项，可以显示全部基金投资的总结表和多样的持仓与交易量化，包括折线图、河流图、饼图、柱形图等。所有可视化均为可交互的 web 级可视化方案。
可以非常简便地制定各种基于日期和点数的定投策略，包括变额定投和复杂的网格策略均可以一行完成，并进行详细的回测分析与可视化展示。
可以基于净值或各种技术指标的交叉、点位设计复杂的交易策略，并回测效果进行定量分析。
可以根据自定义的策略，建立邮件按时提醒脚本，从此实现按计划买入和对市场的实时监控，尤其适合复杂网格策略的执行。
使用通用的金融数据日线 API，轻松获取不同数据进行交叉分析，数据包括但不限于 A 股市场、港股市场和美股市场的指数、基金、股票等标的，A 股的债券和可转债，所有 investing.com、bloomberg.com、spindices.com 上的标的数据，人民币中间价数据，场内基金份额数据。
获取实时的各地市场股票、基金数据，包括计价货币和实时盘外价格。
基于指数权重和企业财报，得到的 A 股各指数历史估值情况和实时估值位置总结。
获取宏观经济数据和计算相应指数的总净资产与总盈利。
QDII 基金的 T-1 日净值预测和 T 日净值实时预测的基础设施。
获取雪球和英为支持标的的、不同频率的近期分时数据，和聚宽源的 A 股任意时间段的分时数据。
获取基金的股票和债券持仓数据，不止十大权重，可以覆盖全部持仓。
获取整个基金组合的底层股票持仓细节统计和不同类型的仓位，用于更底层的审视基金组合或追踪机构持仓。
可转债全自动定价与估值，自动分析可转债内在价值、期权价值、到期收益率等。
支持多基金的完整动态可编程的回测引擎。

九、小结与延伸阅读

xalpha 在 Qbot 仓库中的价值在于把「基金投资研究」抽象成一条可复用的数据链路：fundinfo/indexinfo/vinfo提供统一的标的抽象 →record用最简 csv 账单编码真实交易 →trade精确还原单标的交易行为 →mul/mulfix汇总组合并支持开放/封闭两种资金口径 →policy一行生成策略账单完成回测 →review落地为定时提醒。所有关键约定（指数 7 位代码、netvalue/totvalue双列、账单小数位标记、property 0-7 性质位）均已在 record.py 与 multiple.py 的源码中逐条可查。

建议按以下路径继续深入：

doc/source/demo.rst：基本用法与研究案例的 Notebook 索引（基金信息、组合管理、单标的交易、策略生成等）；
doc/source/advance.rst：数据结构与模块设计的高级用法；
doc/samples：随仓库提供的示例 Notebook 与脚本；
pyfunds/backtest/tests：含demo*.csv账单样例与test_trade.py、test_universal.py等可执行测试，用于核对各 API 行为。

适用前提提醒：xalpha 依赖 Python 3 及 pandas/pyecharts 等第三方库（见 requirements.txt）；通用行情获取器依赖 investing.com、雪球等外部数据源接口，数据可得性受对应站点接口稳定性影响，实际使用前建议先用prev/start等参数小样本验证。

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