---
title: "HMM 双尺度方向"
description: "hmm_regime 接口使用说明：请求示例、参数、返回字段与结果读取。"
---

# HMM 双尺度方向

## 调用示例

使用 `POST /api/indicators` 计算行情指标。设置 `id: "hmm"` 后，从 `indicators.hmm` 读取结果。

```bash
curl -X POST 'https://api.mobiusquant.ai/api/indicators?explain=false' \
  -H 'Content-Type: application/json' \
  -d '{
    "exchange": "binance",
    "market": "perp",
    "symbol": "BTCUSDT",
    "interval": "1h",
    "limit": 100,
    "calc": [{"name": "hmm_regime", "id": "hmm"}]
  }'
```

实时支持 Binance、Bybit、OKX、Hyperliquid 已接入行情的 `5m / 15m / 1h / 4h / 1d`，包含[币安股票永续](/zh/markets#binance-stock-perp)，不包含股票现货。鉴权和通用请求字段见[接入说明](../agents)。

## 参数

以下参数均为可选，放在 `calc[].params` 中。不传时使用默认值。

| 参数 | 类型 | 默认值 | 可选值 / 范围 | 说明 |
| --- | --- | --- | --- | --- |
| `horizon` | integer | `20` | 5–100 | 局部计算尺度；背景尺度为其 3 倍。 |
| `fast_weight` | number | `0.35` | 0–1 | 快变化证据的权重。 |
| `stick` | number | `0.97` | 0.80–0.999 | 状态持续参数；越大越倾向保留已有方向。 |
| `confirm` | integer | `3` | 1–10 | 建立或切换方向所需的连续合格收盘柱数。 |
| `dominance` | number | `0.55` | 0.34–0.95 | 候选方向的最低模型权重。 |
| `margin` | number | `0.15` | 0–0.9 | 候选方向相对第二高权重的最低领先值。 |
| `normalization` | string | `auto` | auto, d1, legacy | 计算模式；auto 按周期选择，也可指定 d1 或 legacy。 |

`normalization: "auto"` 在 5m/15m/1h 使用 d1，在 4h/12h/1d 使用 legacy。
例如指定模式：`{"name":"hmm_regime","id":"hmm","params":{"normalization":"legacy"}}`。

## 返回结果

以下仅展示 `indicators.hmm`，数值用于说明结构，不代表实时行情。
`columns` 与每行 `data` 按位置对应，每行对应一根 K 线。

```json
{
  "columns": [
    "open_time", "hmm_state", "hmm_status",
    "hmm_p_up", "hmm_p_range", "hmm_p_down",
    "hmm_context_state", "hmm_context_status", "hmm_supported"
  ],
  "data": [
    [1735689600000, 1, "confirmed", 0.7, 0.2, 0.1, 1, "confirmed", true]
  ],
  "meta": {
    "schema_version": 3,
    "model_version": "mobius-direction-v2",
    "effective_normalization": "d1",
    "history_start_ms": 1717693200000,
    "history_status": "ready",
    "history_bars": 5000,
    "last_bar_closed": true,
    "last_confirmed_time_ms": 1735689600000
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `open_time` | integer | K 线开盘时间，Unix 毫秒。 |
| `hmm_state` | integer | 当前保留的局部方向。 |
| `hmm_status` | string | 局部状态：unavailable、uncertain 或 confirmed。 |
| `hmm_p_up` | number | 局部上涨模型权重，0～1。 |
| `hmm_p_range` | number | 局部震荡模型权重，0～1。 |
| `hmm_p_down` | number | 局部下跌模型权重，0～1。 |
| `hmm_context_state` | integer | 同一周期、horizon×3 尺度的背景方向。 |
| `hmm_context_status` | string | 背景状态；取值与 hmm_status 相同。 |
| `hmm_supported` | boolean / null | 当前已收盘证据是否支持保留的局部方向，取值见下表。 |

两个方向字段均使用：`-1` 尚无有效方向、`0` 震荡、`1` 上涨、`2` 下跌。
背景是同一周期的较慢尺度，不是另一周期的行情。

三类权重合计约为 1，表示模型对当前类别的相对支持程度，不是未来涨跌概率或胜率。
状态为 unavailable 时，初始的 1/3 权重不构成有效判断。

需要完整历史结果时，请检查 `meta.history_status === "ready"`；否则结果可能变化。
`ready` 不代表方向已确认，方向判断仍需读取 `hmm_status` 和 `hmm_context_status`。

<details>
<summary>meta 字段说明</summary>

| 字段 | 说明 |
| --- | --- |
| `history_status` | 历史数据状态：warming 准备中，ready 完整，partial 不完整。仅行情接口返回。 |
| `history_bars` | 本次实际用于计算的 K 线数量，包含输出窗口之前的历史；仅实时请求返回。 |
| `schema_version` | 响应结构版本，当前为 3。 |
| `model_version` | 计算模型标识，当前为 mobius-direction-v2。 |
| `effective_normalization` | 实际使用的模式：d1 或 legacy。 |
| `history_start_ms` | 本次计算使用的首根 K 线开盘时间，毫秒。 |
| `last_bar_closed` | 返回窗口末根是否已收盘；空窗口为 null。 |
| `last_confirmed_time_ms` | 截至返回窗口末尾，最后已收盘 K 线的开盘时间（毫秒）；无则 null。不是方向切换时间。 |

</details>

## 读取结果

按字段名读取，不要固定数组下标。以下代码将最新一行转换为对象；没有数据时返回 null。

```js
const result = response.indicators.hmm;
const row = result.data.at(-1);
const latest = row
  ? Object.fromEntries(result.columns.map((field, i) => [field, row[i]]))
  : null;

// latest?.hmm_state
// latest?.hmm_supported
```

| 状态 | 含义 |
| --- | --- |
| `unavailable` | 历史数据不足或缺口恢复中，不作方向判断。 |
| `uncertain` | 首次方向仍待确认，或已有方向暂未得到当前证据支持。 |
| `confirmed` | 方向已经确认，且当前证据支持它。 |

| hmm_supported | 含义 |
| --- | --- |
| `true` | 当前证据支持保留的局部方向。 |
| `false` | 已有保留方向，但当前证据不支持；不等于反向已确认。 |
| `null` | 尚无有效方向。 |

例如 `hmm_state=1` 且 `hmm_supported=false`：仍保留上涨方向，但当前证据不足以支持上涨。
默认结果只在收盘后更新；未收盘末根沿用最近已收盘的方向、权重和支持状态。
同时设置 `signals: true`、`include_forming: true` 时，末根当前 OHLCV 作为完整样本参与一次试算，
方向、三类权重、支持状态和特征均来自该次试算，结果可在后续更新时消失。
`confirm` 等模型条件不变，重复请求同根不会增加确认次数。`hmm_status=confirmed` 在此模式下
只表示模型条件满足；末根信号 `bar_status=forming`、`confirmed_at_ms=null`，不是实际收盘确认。
`meta.last_bar_closed` 和 `meta.last_confirmed_time_ms` 仍描述实际输入状态，另带 `meta.include_forming=true`。

## 自带 K 线

调用 `POST /api/indicators/compute`，数据格式见[自带 K 线计算](../compute)。

- 必须显式传入 `interval`，支持 5m/15m/1h/4h/12h/1d；12h 仅支持自带数据计算。
- 默认所有输入均已收盘；仅末根未收盘时，设置请求顶层 `last_bar_closed: false`。
- 仅计算 HMM 时最多 5000 根；混合其他指标时最多 2000 根；每次最多 8 个 HMM 实例。
- 时间戳必须是严格递增的毫秒值，OHLC 必须为正数；不要用重复 K 线填补缺口。

默认 horizon=20 时，d1 的局部/背景输入分别需 20/60 根，legacy 需 153/461 根；
输入就绪后仍需连续方向确认。调整 horizon 会改变所需历史，是否可用以 status 为准。
比较两次结果时，应使用相同数据、历史起点、周期、参数及收盘标记。

## 图表

将调用示例的路径改为 `POST /api/chart`，请求体保持不变。
HMM 副图位于 `panels[]` 中，`id` 对应请求的 `id`（本例为 hmm）。
`items` 包含 Up / Range / Down 三条 line，数值分别对应三类模型权重，范围 0～1。
图表点的 `time` 使用 Unix **秒**，计算结果的 `open_time` 使用**毫秒**。
历史准备状态和输入根数位于 `indicator_meta.hmm`（按请求 id 读取）。


## 特征信号

在计算请求顶层设置 `signals: true`，读取 `indicators[响应key].signals`。默认仅在收盘后判断。`true` 表示事件发生或状态成立，`false` 表示可判断但不成立，`null` 表示不可判断。这些不是买卖指令。

本指标支持 `include_forming: true`：将末根当前 OHLCV 作为完整样本按下表原规则试算，仍输出同一份数值、特征与对象。信号表末尾增加 `bar_status` 列：`closed` 为收盘计算，`forming` 为盘中试算，后者 `confirmed_at_ms=null`，特征可在后续更新或收盘时消失。BYO 末根形成中仍需设置 `last_bar_closed: false`。下表及附注中的收盘要求描述默认模式；试算只放开末根参与资格，不缩短结构窗口或降低模型确认条件。[盘中试算用法](/zh/signals#forming)。

下表历史长度为最低判断要求，不保证平滑值已完全收敛。前后比较使用未舍入数值；阈值恰好相等时按表中边界处理。输入缺口、依赖值无效或默认模式下未收盘时不要把 `null` 转为 `false`。

| 特征列 | 类型 | 判断逻辑 | 代表含义 | 所需历史 / 有效条件 |
| --- | --- | --- | --- | --- |
| `hmm_regime.direction_established` | `event` | hmm_state 从 -1 变为 0/1/2，且本根局部状态可用。 | 连续 confirm 根合格候选首次建立保留方向；不是已有方向翻转。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.direction_changed` | `event` | 前后 hmm_state 均为 0/1/2，且取值改变。 | 已保留的局部方向切换；新方向读取 hmm_state。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.context_established` | `event` | hmm_context_state 从 -1 变为 0/1/2，且本根背景状态可用。 | 同一 K 线周期的较长尺度首次确认，不是跨周期确认。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.context_changed` | `event` | 前后 hmm_context_state 均为 0/1/2，且取值改变。 | 较长尺度保留方向改变；新方向读取 hmm_context_state。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.support_lost` | `event` | 保留方向不变，hmm_supported 从 true 变为 false。 | 证据不再满足原有支持条件，但保留方向尚未切换。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.support_restored` | `event` | 保留方向不变，hmm_supported 从 false 变为 true。 | 同一方向重新得到证据支持，不等同于重新等待 confirm 根或方向切换。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |
| `hmm_regime.evidence_supported` | `state` | 读取 hmm_supported；没有有效保留方向或尚未收盘时为 null。 | true 为支持，false 为暂不支持；不是上涨或下跌预测概率。 | 依赖对应尺度的原始就绪状态；事件需连续两根已收盘输入，支持变化还要求前后为同一有效方向。 |

格式与示例见[特征调用说明](/zh/compute#native-features)。`/api/chart` 同样可设置 `signals: true`，默认只标记已确认事件；开启 `include_forming` 后盘中事件也可生成标记，并带 `bar_status=forming`，状态不逐根绘制。参见[信号绘图](/zh/compute#feature-chart)。