企业官网建设流程全解析

Lean 期货保证金数据维护实战：CME 集团初始/维持保证金 CSV 文件更新指南

【免费下载链接】LeanLean Algorithmic Trading Engine by QuantConnect (Python, C#)项目地址: https://gitcode.com/GitHub_Trending/le/Lean

本指南面向使用 QuantConnect Lean 回测框架维护期货数据的开发者，系统讲解如何从 CME 集团官网（CME、CBOT、NYMEX、COMEX）采集《Performance Bond-Margins》保证金公告，并将其中的初始保证金（Initial Margin）与维持保证金（Maintenance Margin）写入 Lean 数据目录下的期货保证金 CSV 文件。读完本文，你将掌握 PDF 与 Excel 两类公告的完整提取流程、术语口径（前月、夏/冬令时）、数值换算公式，并能理解保证金文件在 Lean 源码中的加载与验证机制，独立完成任意 CME 系期货品种（如CL原油）的历史保证金数据维护。

保证金文件在 Lean 中的角色

期货是杠杆交易品种，交易所会按合约公布初始保证金与维持保证金，回测引擎需要这些数据来计算下单所需的保证金占用、判断是否触发追保（Margin Call）。在 Lean 中，期货保证金数据以 CSV 文件的形式存放在数据目录下，目录结构为：

Data/future/{market}/margins/{symbol}.csv

例如 CBOE 波动率期货（CFE 市场）的保证金文件位于 Data/future/cfe/margins/，其中包含VX.csv与VXM.csv；而 CME、CBOT、NYMEX、COMEX、ICE 等市场的保证金文件则分别位于 Data/future/cme/margins/、Data/future/cbot/margins/ 等目录下。仓库中的市场清单可参考 Data/future/readme.md，其中列举了当前支持的 CBOT、CME、NYMEX、COMEX、CBOE、ICE 等期货市场。

运行时，这些文件由 Common/Securities/Future/FutureMarginModel.cs 读取。其FromCsvFile方法按照下述规则拼接文件路径并加载：

var file = Path.Combine(Globals.DataFolder, symbol.SecurityType.ToLower(), symbol.ID.Market.ToLowerInvariant(), "margins", symbol.ID.Symbol + ".csv");

即按「安全类型（future）→ 市场（如 cme）→ margins → 合约符号」的层级定位。加载时引擎会跳过所有以#开头的注释行与空白行，再跳过首行表头，将每一行数据解析为一条带生效日期的保证金记录，并按日期升序排列后缓存（MarginRequirementsEntry.cs）。保证金规则的生效逻辑是：以合约最近一笔数据的日期为基准，取日期不晚于该日的最后一条记录作为当前保证金要求，因此 CSV 中每一行的日期即该保证金标准生效的起始日。

保证金 CSV 文件格式

保证金文件的列结构如下：

文件首行是表头date,initial,maintenance，可以用#开头的行添加注释。仓库中 Data/future/cfe/margins/VX.csv 给出了一个完整示例：

# we don't have historical information for this symbol date,initial,maintenance 19900101,12000,9600

其中19900101表示该保证金标准自 1990 年 1 月 1 日起生效，初始保证金 12000 美元/张、维持保证金 9600 美元/张。需要注意，本行注释「we don't have historical information for this symbol」表示这只是占位性的默认值，当没有该品种的完整历史保证金数据时，Lean 会退而使用这条单一记录。

此外，CSV 还支持可选的第四、五列用于记录日内保证金（Intraday Margin）。从 MarginRequirementsEntry.cs 的实现看，若文件只有三列，则日内初始保证金与日内维持保证金会默认取隔夜（Overnight）值的 40%：

decimal initialIntraday = initialOvernight * 0.4m; decimal maintenanceIntraday = maintenanceOvernight * 0.4m;

若提供了第四、五列，则按文件中的实际值解析。日内保证金默认不启用（EnableIntradayMargins默认为false），启用后交易所开盘且临近收盘之外的时间段会使用更低的日内保证金，可能带来保证金占用减少但回撤时更容易触发追保的效果（见 FutureMarginModel.cs 中的取值分支）。

从 CME 官网获取保证金公告

CME 集团（包含 CME、CBOT、NYMEX、COMEX）会在其官网发布包含各品种初始与维持保证金变动的公告（Advisory），发布栏目为：

Clearing -> Performance Bond-Margins

这些公告对应「Performance Bonds/Margins」FAQ 中关于初始保证金与维持保证金用法的官方说明。请注意：本教程只覆盖自 2008 年起的保证金数据采集，如需更早的历史数据，需另寻途径。

搜索公告的操作流程

1. 打开 CME 官网的「Notices」公告检索页，在检索条件中将起始日期设置为期望数据开始日期之前的几个月（若为新上市合约，则设置为合约上市前的几个月），避免遗漏最早的保证金变动公告。
2. 在检索页中输入合约所属的品种类别关键词。CME 按商品类别（如Natural Gas, Refined Products, Agriculture, Coal, Interest Rates等）列出受保证金变动影响的期货类别，按类别搜索可显著加速历史保证金数据的采集。以本教程的示例CL（NYMEX 原油期货）为例，可以直接搜索Crude。
3. 若检索结果没有覆盖到当前年份，应将检索词放宽到更宽泛的类别，例如把Crude改为Energy；若仍然无效，则可以省略检索词，逐条人工浏览每个公告，寻找目标合约代码。
4. 在结果列表中定位名为Performance Bond Requirement Changes的公告，记录其中的Effective Date（生效日期），该日期就是要写入保证金文件date列的值。
5. 点击公告中「For the full text of this advisory, please click here.」链接查看完整内容。

CME 提供两种格式的保证金公告：

• PDF 格式：适合按步骤逐条核对文字型表格。
• Excel 格式：适合通过「Table of Contents / Outright」选项卡与缩放因子快速换算数值。

两种格式各有独立的提取流程，下面分别展开。

使用 PDF 公告更新保证金

前置术语

在开始之前，需要先理解 CME 公告中的几组术语口径：

• Summer（夏令时段）：CME 将4 月 - 10 月划定为 Summer。
• Winter（冬令时段）：CME 将11 月 - 次年 3 月划定为 Winter。
• Front Month（前月/主力月）：距离到期日最近的合约月份。
• Mth 1 / Mnth 1 / Month 1：均指前月（主力月）；月份数字每递增 1，代表紧随前月之后的下一月份合约。

七步核对流程

在将公告数值录入保证金 CSV 文件之前，须逐项执行以下检查。若其中任何一步失败，则跳过该公告，继续查看下一条公告（通常意味着该公告中的条目并不适用于目标合约）：

1. 检索合约代码：在公告正文中搜索用括号包裹的合约代码，例如(CL)。
2. 确认是 Outrights（单腿净头寸）：确保该条目属于Outrights类别。
3. 排除复合合约条目：确认该合约不是其他合约的组成部分。例如Crude Oil (CL) vs. WTI Houston (Argus) Financial (HIA)这类价差/复合合约条目不适用于CL合约，必须排除。
4. 确认存在 Spec 条目：确保该合约数据中至少有一条Spec记录（注意Spec在公告中也可能写作Speculation，即投机性持仓）。
5. 定位前月条目：找到描述中包含Month 1的条目。
6. 录入初始保证金：将 PDF 中的new initial margin（新初始保证金）数值填入 CSV 文件的initial列。
7. 录入维持保证金：将 PDF 中的new maintenance margin（新维持保证金）数值填入 CSV 文件的maintenance列。

示例中CL在 PDF 公告内的条目即遵循上述结构：先出现(CL)合约代码，随后是Outrights类别下的Spec记录，其中Month 1对应的两列数值即为需要录入的新初始/维持保证金。

使用 Excel 公告更新保证金

前置条件

处理 Excel 格式公告需要以下任一工具：

• Microsoft Excel
• LibreOffice
• Google Sheets

八步换算流程

Excel 公告中通常包含「Table of Contents」总览选项卡与各交易类型的明细选项卡，其数值需要通过「缩放因子（Scaling Factor）」和「初始保证金百分比」换算后才能写入 CSV。流程如下，同样遵循"任一步骤失败则跳过该公告"的原则：

1. 记录初始保证金百分比：查找公告中提及initial margin的说明文字并记录其数值，通常为110%。

2. 在 Table of Contents 选项卡中检索合约代码：切换到Table of Contents选项卡，在表格的Product Code（产品代码）列中搜索目标合约代码。

3. 记录 Combined Commodity 值：记下该产品代码对应的Combined Commodity（组合商品）值。

4. 记录缩放因子：记下该产品的Scaling Factor（缩放因子）。示例中CL在Table of Contents选项卡的条目即包含Product Code、Combined Commodity与Scaling Factor三列信息。

5. 切换到 Outright 选项卡：切换到工作簿的Outright选项卡；如果不存在Outright选项卡，则继续下一条公告。

6. 定位匹配条目：在Outright选项卡中找到第一条Combined Commodity与第 3 步记录值一致的条目。

7. 计算维持保证金：将New Margin（新保证金）乘以Scaling Factor，结果填入 CSV 文件的maintenance列：

   maintenance = New Margin × Scaling Factor

8. 计算初始保证金：将New Margin乘以Scaling Factor，再乘以第 1 步记录的Initial Margin百分比，结果填入 CSV 文件的initial列：

   initial = New Margin × Scaling Factor × Initial Margin(%)

以CL为例：若Table of Contents中记录的Scaling Factor为 1000，公告中Outright选项卡的New Margin为 7（千美元级），初始保证金百分比为 110%，则维护保证金为7 × 1000 = 7000，初始保证金为7 × 1000 × 1.10 = 7700，将7700与7000分别写入initial与maintenance列，并把公告的Effective Date写入date列。

数据写入与生效日期规则

无论采用 PDF 还是 Excel 流程，最终都需要把数值追加或修正到目标合约的保证金 CSV 文件中，并遵守以下规则：

• date 列：使用公告中的Effective Date（生效日期），格式为YYYYMMDD。引擎会按日期升序读取所有记录，并以"日期不晚于当前交易日期的最新一条"作为生效标准，因此同一品种的多条记录必须按时间先后排列。
• initial 列：每张合约的初始保证金（美元）。
• maintenance 列：每张合约的维持保证金（美元）。
• 可选列：第四列initial intraday、第五列maintenance intraday可省略，省略时自动取隔夜值的 40%。

写入完成后可参考仓库现有文件核对格式，例如 Data/future/cfe/margins/VX.csv 与 Data/future/cfe/margins/VXM.csv（后者的初始/维持保证金分别为 1200/960 美元）。注意在维护数据时不要破坏#注释行（如示例中的说明性注释），因为引擎会跳过注释行而非报错。

仓库中的数据合法性校验

Lean 仓库通过单元测试对保证金文件的格式与数值合法性进行自动校验，相关测试位于 Tests/Common/Securities/FutureMarginBuyingPowerModelTests.cs。其中FutureMarginModel_MarginEntriesValid测试会遍历 CBOT、CFE、COMEX、NYMEX、Globex 等市场的margins/*.csv文件，逐行断言：

• 每行至少包含 3 列（date,initial,maintenance）；
• 日期必须能以YYYYMMDD格式解析，且不早于 1990-01-01；
• 初始保证金与维持保证金必须严格大于 0。

这从侧面印证了保证金 CSV 的最低格式要求：即使某品种缺少完整历史数据（如VX.csv中仅有一行19900101,12000,9600的占位记录），也至少要保证表头、列数与数值的正规性，测试才能通过。

此外，FutureMarginBuyingPowerModelTests.cs 中的IntradayVersusOvernightMargins与ClosingSoonIntradayClosedMarketMargins等用例验证了日内/隔夜保证金的选择逻辑：启用EnableIntradayMargins后，交易时段内使用较低的日内保证金，临近收盘或休市时退回隔夜保证金——理解这一行为有助于判断保证金文件的数值口径（录入的是隔夜标准）。

总结

维护 CME 集团期货的保证金数据，本质上是把交易所公告中的数值按统一口径换算并落盘到Data/future/{market}/margins/{symbol}.csv。核心要点可以归纳为四条：

1. 来源唯一：从 CME 官网Clearing -> Performance Bond-Margins下的Performance Bond Requirement Changes公告采集，注意Effective Date即生效日期。
2. 口径清晰：PDF 流程认准(代码)、Outrights、Spec、Month 1四个关键词；Excel 流程走Table of Contents -> Outright两级选项卡，配合Scaling Factor与初始保证金百分比完成换算。
3. 格式合规：date,initial,maintenance三列齐全、日期为八位YYYYMMDD、数值为正，可选日内保证金列（缺省为隔夜值的 40%）。
4. 可验证：通过仓库自带的FutureMarginModel_MarginEntriesValid测试可以批量校验所维护文件的数据合法性。

遵循上述流程，即可为 Lean 回测补充准确的期货保证金历史数据，使保证金占用与追保判断在历史回测中与真实交易所规则保持一致。

【免费下载链接】LeanLean Algorithmic Trading Engine by QuantConnect (Python, C#)项目地址: https://gitcode.com/GitHub_Trending/le/Lean