QuantLib · Rate & vol models
QuantLib 利率模型与 Heston 波动率模型：参数含义、实测校准与微笑
利率模型和波动率模型最容易出错的地方不是公式，而是「参数到底是干什么的、量级该填多少、结果为什么和别人的不一样」。本页用 QuantLib 1.43 在本机跑出的实测数据，把 Hull-White 的均值回复速度与波动率、Heston 的五个参数、Feller 条件、互换期权定价与波动率微笑逐项对上号，并给出两组真实踩坑记录。
利率类工具靠曲线 + 短率模型定价，期权类工具靠随机波动率模型定价；两条线的参数含义与校准目标不同，把模型的参数当「拟合旋钮」乱调，是结果对不上的常见原因。示意图为本站绘制，非实盘界面。
QuantLib 有哪些利率与波动率模型可用？
下表按「模型类型 → QuantLib 类名」整理。类名一列是本机 `dir(QuantLib)` 实测存在的结果，最后一列如实标注本站做了哪一档验证：只核验类名存在的不等于本站验证过其定价结果。
| 模型 | QuantLib 类（本机实测存在） | 适用场景 | 注意点 | 本站验证程度 |
|---|---|---|---|---|
| Hull-White（单因子短率） | ql.HullWhite | 互换期权、上限/下限期权等利率衍生品定价 | 只有均值回复速度 a 与波动率 σ 两个参数，波动率期限结构不能自由拟合 | 已实测定价（下表 8 组参数） |
| Vasicek（单因子短率） | ql.Vasicek | 短率均值回复的教学与解析推导 | 利率可以为负；本机实测把它直接配 Jamshidian 引擎会报错（见排查表） | 已实测参数与报错 |
| CIR（平方根扩散） | ql.CoxIngersollRoss / ql.ExtendedCoxIngersollRoss | 希望短率不为负的均值回复建模 | 参数需满足平方根扩散的存在性条件，本站未验证 | 只核验类名存在 |
| Black-Karasinski | ql.BlackKarasinski | 对数正态短率的利率建模 | 无解析债券价格，通常走树/有限差分；本站未验证 | 只核验类名存在 |
| G2（两因子短率） | ql.G2 | 需要两因子相关性结构的产品 | 参数更多、校准数据要求更高；本站未验证 | 只核验类名存在 |
| Heston（随机波动率） | ql.HestonProcess + ql.HestonModel | 股指/外汇期权的偏斜与微笑建模 | 解析引擎不提供 delta/vega/gamma（本机实测报错），风险要用差分或其它引擎 | 已实测定价与微笑（下表） |
| Bates（随机波动率 + 跳跃） | ql.BatesModel | 需要跳空特征的期权定价 | 参数比 Heston 更多，校准更依赖数据；本站未验证 | 只核验类名存在 |
| SABR（微笑插值） | ql.SabrSmileSection / ql.SABRInterpolation | 只拟合市场微笑形状（不建动态过程） | 它是插值/拟合工具，不要当动态模型用来定价路径依赖产品 | 只核验类名存在 |
| Heston + Hull-White 组合 | ql.AnalyticHestonHullWhiteEngine / ql.FdHestonHullWhiteVanillaEngine | 同时含随机波动率与随机利率的期权 | 组合模型参数更多；本站未验证 | 只核验类名存在 |
什么场景该选哪个模型？
下面这张表把常见任务、可用模型、选择理由与限制放在一起。理由一列写的是「为什么这个模型能回答这个问题」，限制一列写的是它答不了什么。
| 任务场景 | 可选模型 | 选择理由 | 限制 / 注意点 |
|---|---|---|---|
| 给互换期权（Swaption）定价 | Hull-White | 单因子仿射模型与初始曲线一致，有 Jamshidian 这类解析引擎，速度快、参数可解释 | 波动率结构由 a 与 σ 两个参数决定，无法自由拟合整条波动率微笑 |
| 给互换期权定价但曲线水平很低（如 2%） | Hull-White | 模型以曲线为初始条件，报价水平/行权价的实值虚值程度会直接反映到价格上 | 本机实测：曲线 0.5% 时价格 9e-08、6% 时才 6.67686296，量级跨 8 个数量级，别用「一眼看是否合理」判断 |
| 教学演示短率的均值回复与解析性质 | Vasicek | 参数少、解析形式完整，便于手算验证 | 允许负利率；把无曲线的 Vasicek 直接塞给需要期限结构的引擎会报错（本机实测） |
| 要求短率不为负 | CIR / ExtendedCoxIngersollRoss | 平方根扩散天然排除负值 | 本站未验证；参数存在性条件需自查，以官方文档为准 |
| 刻画股票/外汇期权的偏斜（skew） | Heston | ρ 直接控制偏斜方向与幅度，本机实测三组 ρ 给出三种微笑形状 | 解析引擎不提供希腊字母；平值附近差异小、两翼差异大，只看平值会低估模型差异 |
| 需要跳空 + 微笑 | Bates | 在 Heston 基础上加入跳跃成分 | 本站未验证；参数更多、校准数据要求更高 |
| 只需要一条能用的市场微笑（不建动态） | SABR 插值（SabrSmileSection / SABRInterpolation） | 直接拟合市场报价形状，实现简单 | 它是「拟合/插值」，不要用它去给路径依赖产品定价 |
| 两因子相关性结构（更复杂的曲线变形） | G2 | 两因子可表达更丰富的曲线形变 | 本站未验证；校准难度明显上升 |
Hull-White 互换期权实测：a 与 σ 各自改变什么？
同一笔 5Y×5Y 互换期权（Payer、固定利率 4.5%、TARGET 日历、平曲线 3%、估值日 2024-01-15），只改 Hull-White 的两个参数，用 Jamshidian 解析引擎定价。数值全部来自本机运行。
| 均值回复速度 a | 波动率 σ | 互换期权 NPV | 模型直接回报的参数 | 读法 |
|---|---|---|---|---|
| 0.01 | 0.001 | 0.0 | [0.01, 0.001] | σ 太小：时间价值被压到 0，注意这**不是**报错 |
| 0.05 | 0.005 | 0.00033822 | [0.05, 0.005] | 量级仍是「分」级别，容易被误认为算坏了 |
| 0.05 | 0.01 | 0.09028313 | [0.05, 0.01] | σ 翻倍，价格放大约 267 倍（凸性驱动） |
| 0.1 | 0.005 | 0.00004532 | [0.1, 0.005] | a 变大、σ 不变：价格反而下降到 4.5e-05 |
| 0.1 | 0.01 | 0.04386872 | [0.1, 0.01] | 本页基准行，后续曲线敏感性以它为起点 |
| 0.1 | 0.02 | 0.66856569 | [0.1, 0.02] | σ 再翻倍：放大到 0.67，约 15 倍 |
| 0.2 | 0.02 | 0.30354143 | [0.2, 0.02] | a 从 0.1 增到 0.2 使同 σ 下价格回落 |
| 0.3 | 0.03 | 0.51827739 | [0.3, 0.03] | 两参数同时上升，价格回升但低于 a=0.1/σ=0.02 |
| 平曲线水平 | 互换期权 NPV | 读法 |
|---|---|---|
| 0.5% | 0.00000009 | 深度虚值：固定利率 4.5% 远高于曲线，几乎无价值 |
| 1.0% | 0.00000268 | 仍是极小值 |
| 1.5% | 0.00005442 | 开始抬升 |
| 2.0% | 0.00074261 | 比 1.5% 高约 13 倍 |
| 3.0% | 0.04386872 | 本页基准行（与上表 a=0.1/σ=0.01 同一配置） |
| 4.0% | 0.63771114 | 接近平值，价格抬升约 14.5 倍 |
| 5.0% | 2.9798904 | 深度实值 |
| 6.0% | 6.67686296 | 继续上升，曲线水平的影响远大于参数微调 |
每个参数是什么意思、量级该填多少、数据从哪来？
模型校准失败往往不是算法问题，而是参数的量级或来源搞错了（例如把「年化波动率 10bp」写成 10）。下表把本页涉及的全部参数逐个列出，其中「本站实测值」一列的数值都是本机跑出来的。
| 参数 | 物理含义 | 典型量级 / 单位 | 数据从哪来 | 本站实测值 |
|---|---|---|---|---|
| a（Hull-White） | 短率的均值回复速度 | 0.01 ~ 0.5（每年），量纲是 1/年 | 由利率产品的市场价格反推（校准） | 本页实验用 0.01 / 0.05 / 0.1 / 0.2 / 0.3 |
| σ（Hull-White） | 短率的绝对波动率 | 0.001 ~ 0.03（绝对值，**不是**百分数） | 由互换期权/上限期权的隐含波动率反推 | 本页实验用 0.001 / 0.005 / 0.01 / 0.02 / 0.03 |
| r0（Vasicek 首参） | 初始短率水平 | 与曲线水平同量级（小数） | 取曲线上的短端利率 | 本页实验用 0.03 |
| a（Vasicek） | 均值回复速度 | 同 Hull-White 的 a | 校准 | 本机 ql.Vasicek(0.03, 0.1, 0.01) 的 params() 回报 [0.1, 0.01, 0.01, 0.0]；按构造函数顺序首分量即 a |
| b / 长期均值（Vasicek） | 短率回复的目标水平 | 与曲线水平同量级 | 校准或直接取长期均值 | 同上回报向量的第 2 个分量为 0.01（分量与参数名的对应关系以官方文档为准） |
| λ（Vasicek） | 风险市场价格（风险溢价项） | 小数，可为 0 | 一般设 0 表示风险中性测度下无溢价 | 同上回报向量的第 4 个分量为 0.0 |
| v0（Heston） | 初始方差（不是波动率） | 0.01 ~ 0.25（方差），波动率 20% 对应 v0=0.04 | 由短期隐含波动率折算（σ²） | 本页实验用 0.04，对应波动率 20% |
| κ / kappa（Heston） | 方差均值回复速度 | 0.5 ~ 5（1/年） | 校准 | 本页实验用 1.5 |
| θ / theta（Heston） | 方差的长期均值 | 与 v0 同量级（方差） | 由长期隐含波动率折算 | 本页实验用 0.04 |
| σ / vol-of-vol（Heston） | 方差的波动率（vol-of-vol） | 0.1 ~ 0.7（1/√年） | 校准，主要影响微笑的两翼高度 | 本页实验用 0.30 |
| ρ / rho（Heston） | 资产价格与方差的相关系数 | -1 ~ 1，负值产生下跌时波动率上升的偏斜 | 校准，主要影响偏斜方向 | 本页实验用 -0.60 / -0.20 / +0.40 三组对照 |
| 2κv0 − σ²（Feller 条件） | 判断方差过程是否「离零足够远」的组合量 | 大于 0 为满足条件 | 由上面参数直接计算，不是独立输入 | 本页实验为 0.03（满足）；另有一组为 -2.248（违反，见排查表） |
Heston 波动率微笑实测：ρ 决定偏斜方向
用同一组 Heston 参数（v0=0.04、κ=1.5、θ=0.04、σ=0.30），只改相关系数 ρ，把每个行权价上的 Heston 价格反解成 Black-Scholes 隐含波动率，就得到三条形状不同的微笑曲线。数值为本机实测。
| 行权价 K | ρ = -0.60 隐含波动率 | ρ = -0.20 隐含波动率 | ρ = +0.40 隐含波动率 | ρ = -0.60 时的 Heston 价格 |
|---|---|---|---|---|
| 80（深度实值） | 22.918213% | 21.400326% | 18.212049% | 25.05149502 |
| 90 | 21.259766% | 20.316718% | 18.405302% | 17.06447962 |
| 100（平值） | 19.724869% | 19.523621% | 19.050428% | 10.36484148 |
| 110 | 18.367395% | 19.069215% | 19.947416% | 5.41036518 |
| 120（深度虚值） | 17.272629% | 18.94056% | 20.914275% | 2.35951629 |
| 微笑斜率（K=120 减 K=80，百分点） | -5.6456 | -2.4598 | +2.7022 | — |
同一期权，Heston 与平波动 Black-Scholes 差多少？
把上面 Heston（ρ=-0.60）的价格与「用 20% 平波动 Black-Scholes」的价格并排比较。这张表说明了什么时候「用 Black-Scholes 近似一下」还能接受、什么时候不能。
| 行权价 | Heston（ρ=-0.60） | Black-Scholes（平波动 20%） | 差值 | 相对差 | 读法 |
|---|---|---|---|---|---|
| 80 | 25.05149502 | 24.60192008 | +0.44957494 | +1.83% | 实值：Heston 略高 |
| 90 | 17.06447962 | 16.71568857 | +0.34879105 | +2.09% | 差异仍小 |
| 100（平值） | 10.36484148 | 10.46814839 | -0.10330691 | -0.99% | 差异最小，容易误判「两个模型一样」 |
| 110 | 5.41036518 | 6.05625835 | -0.64589317 | -10.67% | 虚值：平波动高估 |
| 120 | 2.35951629 | 3.26030327 | -0.90078698 | -27.63% | 深虚值：相对差接近三成 |
| 最大绝对差 / 最大相对差 | — | — | 0.90078698（K=120） | -27.63%（K=120） | 派生行：由上行数值计算 |
两个本机实测踩到的坑：参数顺序，与「不报错但没意义」
下面这条是最容易犯、又最难发现的错误：HestonProcess 的前两个参数都是曲线，顺序传反不会报错，但等于把无风险利率与分红率互换，价格会整体偏低。第二个坑是违反 Feller 条件后依然能算出价格。
| 行权价 | 正确：r=5%、q=0 | 传反：r=0、q=5% | 差值 | 占价格比 | 为什么 |
|---|---|---|---|---|---|
| 80 | 25.05149502 | 17.34836864 | -7.70312638 | -30.75% | 远期从 105.141512 掉到 95.109913 |
| 90 | 17.06447962 | 10.14432877 | -6.92015086 | -40.55% | 同一原因，实值部分被削掉 |
| 100（平值） | 10.36484148 | 4.94091535 | -5.42392613 | -52.33% | 平值期权对远期最敏感 |
| 110 | 5.41036518 | 1.93168287 | -3.47868231 | -64.30% | 虚值放大 |
| 120 | 2.35951629 | 0.61550288 | -1.74401341 | -73.91% | 深虚值几乎被抹平 |
| 远期对照 | 105.141512（=100×e^(0.05T)） | 95.109913（=100×e^(-0.05T)） | — | — | 判据：先打印远期，再比价格 |
| 情形 | 是否报错 | 本机实测结果 | 该怎么判 |
|---|---|---|---|
| 违反 Feller 条件（v0=0.01, κ=0.1, θ=0.01, σ=1.5, ρ=-0.9，2κv0−σ² = -2.248） | 不报错 | 平值看涨 5.47602907（平波动基准 10.46814839） | 先算 2κv0−σ²；为负时价格不可信，别只看「有输出」 |
| Hull-White 参数极小（a=0.01, σ=0.001） | 不报错 | 互换期权 0.0 | 确认 σ 的量级是绝对值 0.001 而非 1 |
| Heston 参数顺序传反 | 不报错 | 平值 4.94091535（正确 10.36484148） | 打印远期：105.14 才是 r=5%、q=0 |
| 给无曲线的 Vasicek 配需要期限结构的引擎 | 报错 | RuntimeError: empty Handle cannot be dereferenced | 模型要么自带曲线（Hull-White 形式），要么显式挂定期限结构 |
| Heston 解析引擎取希腊字母 | 报错 | RuntimeError: delta not provided（vega、gamma 同样） | 用中心差分或换有限差分/MC 引擎；别写 try 之外的空值处理 |
| 用错误的远期去反解隐含波动率 | 报错 | RuntimeError: negative Put price (-6.5637) implied by put-call parity. No solution exists for Call strike 80, forward 105.142, price 17.3484, deflator 0.951099 | 反解隐含波动率前先把远期与折现因子对齐；远期算错时会得到「无解」而不是错误的价格 |
校准流程：从市场价格到模型参数
校准是把「市场价格」翻译成「模型参数」的过程。下面八步是本站在本机跑通的最小闭环，每一步都给出可执行动作与预期结果；同时提醒一句：校准结果只在你的目标函数与权重下成立，换一套权重就可能得到另一组参数。
1. 固定定价环境与估值日
先设ql.Settings.instance().evaluationDate，并固定曲线的计息约定（本页实验统一用 Actual/365 Fixed）。预期：dc.yearFraction(today, ql.Date(15, 1, 2025)) 输出 1.00273973。2. 准备曲线与工具
用平曲线或自建曲线构造YieldTermStructureHandle，再构造待校准的期权/互换期权工具。预期：工具在给定曲线下能算出 NPV（本页互换期权示例为 0.04386872）。3. 明确校准目标与权重
写下目标函数：哪些报价参与校准、用绝对价格差还是波动率差、是否加权（虚值期权价格小、绝对差会被平值主导，通常改用隐含波动率差或按 vega 加权）。这一步必须在代码里写清楚，否则复现不了。4. 设定参数的初始值与上下界
Heston 的 v0 取短端隐含方差、θ 取长期隐含方差、κ 与 σ 给经验量级、ρ 负值起步；Hull-White 的 a 取 0.01~0.3、σ 取 0.001~0.03。预期：初始值下能算出有限价格，不是 0 也不是 inf。5. 选择优化器并记录收敛信息
QuantLib 提供ql.LevenbergMarquardt 等优化器（本机 dir 实测存在）；务必打印迭代次数、最终误差与是否收敛。预期：误差应随迭代下降，而不是在边界值上停留。6. 用「未参与校准」的报价做样本外检验
把一部分行权价/期限留出来，只看样本外误差。预期：样本外误差与样本内同量级才是可用校准；差几倍说明过拟合。7. 做参数敏感性检查
把每个参数单独扰动一点，看价格变化方向是否符合经济直觉（例如 ρ 越负两翼越倾斜）。预期：本页实测三组 ρ 给出斜率 -5.6456 / -2.4598 / +2.7022 个百分点，符号与方向应一致。8. 固化口径：记录曲线日期、数据来源、权重与版本
把「用了哪天哪条曲线、哪些报价、什么权重、QuantLib 与 Python 版本」写进报告。预期：别人拿到记录能复现出同一组参数——这是本页所有实测数字都遵守的规则。常见问题
Feller 条件是什么？不满足会怎样？
Feller 条件一般写作 2κθ − σ²（对 Heston 的方差过程）大于 0，用来确认方差过程「不会频繁贴到 0」。本机实测：v0=0.04、κ=1.5、θ=0.04、σ=0.30 时组合量 2κv0−σ² = 0.03（满足）；换成 v0=0.01、κ=0.1、θ=0.01、σ=1.5 时该量变为 -2.248（违反），此时平值看涨仍能算出 5.47602907，不报错但结果不可信。判据：算价格之前先算这个组合量。具体定义与适用形式以官方文档为准。QuantLib 与 EasyClaw 无已证实集成，这类参数检查需要自己掌握。
为什么 Heston 的解析引擎算不出 delta 和 vega？
本机实测：ql.AnalyticHestonEngine 下调用 option.delta() 抛 RuntimeError: delta not provided，vega()、gamma() 同样不可用。替代做法：①自己用中心差分（设 spot ±0.01、vol ±0.0001 再重新定价）；②换用本机实测存在的ql.FdHestonVanillaEngine 或 ql.MCEuropeanHestonEngine 等引擎。具体哪些引擎提供哪些希腊字母，以官方文档为准。
校准一组 Heston 参数需要多少期权数据？
至少覆盖「不同行权价 + 不同期限」，否则 ρ 与两翼参数不可辨识：只有平值报价时，多组参数都能拟合出同一个价格。本页实测中三组 ρ（-0.60 / -0.20 / +0.40）的平值隐含波动率都在 19%~19.7% 附近，但两翼斜率从 -5.6456 到 +2.7022 个百分点——这正说明必须用两翼数据才能定出 ρ。样本量没有绝对标准，取决于你要求的价格误差与期限覆盖，以你的交易与风控口径为准。
Hull-White 的 σ 该填 0.01 还是 1（百分点）？
填绝对值：本机实测 ql.HullWhite(yts, 0.1, 0.01) 的两个参数直接以 params() 回报为 [0.1, 0.01]，σ=0.01 表示 100bp 等级的年化短率波动率。若按「百分点」填 1，等于把波动率放大 100 倍，价格会离谱但不报错。判据：先用已知量级（0.001~0.03）试探，再看价格是否落在合理范围。
为什么曲线水平一变，互换期权价格能差 8 个数量级？
因为互换期权的价值同时由「实值/虚值程度」和「波动率」决定。本机实测固定 a=0.1、σ=0.01，曲线从 0.5% 升到 6% 时价格从 9e-08 升到 6.67686296；同一曲线（3%）下 σ 从 0.005 变到 0.01，价格从 0.00033822 变到 0.09028313。所以「价格几乎为 0」时先看是不是深度虚值，而不是先调参数。具体数值随你的固定利率与曲线口径变化，以你的交易文件为准。
Vasicek 要不要配期限结构？
要，而且方式有限制。本机实测：把不带曲线的 ql.Vasicek(0.03, 0.1, 0.01) 直接配 ql.JamshidianSwaptionEngine，会在定价时报 RuntimeError: empty Handle cannot be dereferenced；而 Hull-White 的构造 ql.HullWhite(yts, a, sigma) 本身就以曲线为初始条件，可直接用同一引擎。也就是说：选哪条路线，要看你手上有没有曲线、以及引擎是否要求模型自带期限结构。以官方文档为准。
本页的参数是不是「正确」的市场校准参数？
不是。本页所有模型参数都是人为设定的受控实验参数（Heston v0=0.04、κ=1.5、θ=0.04、σ=0.30、ρ 三档；Hull-White a 与 σ 八组），目的只是让「参数变化 → 价格变化」的因果关系可复现、可核对。真实校准需要你的市场数据、目标函数与权重，结果仅供研究与方法论参考，不构成投资建议。