企业官网建设流程全解析

• 机器学习
• 人工智能

导读

本文围绕 nupic-legacy 仓库中 Online Prediction Framework（OPF）的 API 文档体系展开，系统梳理 OPF 对外暴露的核心类（HTMPredictionModel、ModelFactory）以及支撑在线学习与预测的整套运行框架：模型描述（Description API）、实验运行器（Experiment Runner）、任务驱动与运行环境（OPF Task Driver / Environment）、预测指标（Metrics）、结果对象（ModelResult）与异常体系。OPF 是基于 Network API 构建的纯 Python 便捷库，用于组装 HTM 等在线学习算法并产出预测；读完本文，你将掌握如何用ModelFactory按配置字典创建模型、如何用runExperiment命令行运行一个实验、如何配置 encoder/SP/TM/classifier 参数，以及如何通过 Metrics 与异常 API 正确对接 OPF 的完整生命周期。

OPF 概览：定位、设计目标与两种运行形态

根据 OPF API 索引文档，OPF 是一个纯 Python 的便捷库，它不重复实现 HTM 算法本身，而是借助Network API（即nupic.engine.Network，参见 网络 API 文档）来构造常用模型。它向使用者暴露的两个核心类是：

• HTMPredictionModel：用于时序多步预测的 HTM 预测模型；
• ModelFactory：根据配置字典生产模型实例的静态工厂类。

OPF 的设计目标体现在三个方面（原文档原话）：

1. 既嵌入大架构，也能独立运行——它可以作为更大系统中的一个组件被调用，也可以脱离任何框架直接从命令行独立运行；
2. 可扩展性——新增模型算法与功能只需极少的代码改动；
3. 面向在线学习——OPF 是为"边接收数据边学习、边预测"的在线学习算法（包括 HTM）而设计的预测框架。

这两种运行形态在仓库中都能找到对应落点：

• 独立运行：scripts/run_opf_experiment.py是 OPF 的命令行客户端，其入口只是简单调用nupic.frameworks.opf.experiment_runner.main()（见 scripts/run_opf_experiment.py）；
• 嵌入使用：应用代码可以直接ModelFactory.create(modelConfig)创建模型，再按需enableInference、run，把 OPF 作为库函数嵌入自己的预测流程。

OPF 的完整 API 分层由索引页的 toctree 组织为九个主题：models、clients、description-api、exp-runner、environment、metrics、results、utils、exceptions，下文逐一展开。

模型层（Models）：ModelFactory 与四类模型

Models 文档 列出了模型层的全部公开类型，核心是ModelFactory、基类Model以及三个具体模型。

ModelFactory：按配置字典创建模型

ModelFactory是 OPF 模型体系的统一入口，其源码位于 src/nupic/frameworks/opf/model_factory.py。它对外提供两个静态方法：

• ModelFactory.create(modelConfig, logLevel=logging.ERROR)：接收一个描述模型的配置字典，返回一个Model实例。它会根据modelConfig['model']字段选择模型类，然后以modelConfig['modelParams']作为关键字参数实例化：
  • "HTMPrediction"→HTMPredictionModel
  • "TwoGram"→TwoGramModel
  • "PreviousValue"→PreviousValueModel
  • 其他值 → 抛出Exception("ModelFactory received unsupported Model type: ...")
• ModelFactory.loadFromCheckpoint(savedModelDir, newSerialization=False)：从保存的实验目录加载模型；当newSerialization=True时走HTMPredictionModel.readFromCheckpoint的 capnp 新序列化路径，否则走Model.load的传统路径。

从源码看，create()与loadFromCheckpoint()的分工非常清晰：前者负责"从描述创建"，后者负责"从检查点恢复"，二者共同支撑了 OPF 实验的可重复运行能力。

基类 Model 与三个具体模型

• Model（src/nupic/frameworks/opf/model.py）：所有 OPF 模型的基类，定义了统一的生命周期接口。HTMPredictionModel的文档特别强调：模型创建后必须调用enableInference指定预测字段，例如model.enableInference({"predictedField": "myPredictedField"})，其中myPredictedField必须是数据输入中存在的字段名。

• HTMPredictionModel（src/nupic/frameworks/opf/htm_prediction_model.py）：面向"多步 ahead 的时序预测"的模型，是 OPF 的旗舰模型。其构造参数直接对应配置字典中的modelParams：

  • inferenceType：推断类型（见下文InferenceType）；
  • sensorParams：传感器参数（数据集读取方式）；
  • spEnable/spParams：是否启用空间池化器（Spatial Pooler，SP）及其参数；
  • tmEnable/tmParams：是否启用时序记忆（Temporal Memory，TM）及其参数；
  • clEnable/clParams：是否启用分类器（Classifier）；若为 False 则不会创建分类器、不产生预测。

  文档 API 重点列出的一组运行时接口包括：getParameter、getRuntimeStats，以及专用于异常检测的setAnomalyParameter(param, value)、getAnomalyParameter(param)、anomalyRemoveLabels(start, end, labelFilter)、anomalyAddLabel(start, end, labelName)、anomalyGetLabels(start, end)。这些异常标注接口的调用前提是模型必须为 TemporalAnomaly 推断类型且有可用的异常检测器——在源码中由requireAnomalyModel装饰器强制执行（htm_prediction_model.py），不符合条件会抛出RuntimeError。

• TwoGramModel（src/nupic/frameworks/opf/two_gram_model.py）：二元文法基准模型，作为 HTM 预测能力的对照基线。

• PreviousValueModel（src/nupic/frameworks/opf/previous_value_model.py）："上一时刻值"朴素基准模型，同样用于算法对比。

模型描述与 Description API：实验的"说明书"

OPF 实验中所有关于"用什么模型、什么编码器、什么数据集"的声明都集中在实验目录下的description.py中，而 Description API 文档 定义了读取与校验这份说明书的接口：

• DescriptionIface：描述接口的抽象协议；
• ExperimentDescriptionAPI（src/nupic/frameworks/opf/exp_description_api.py）：具体实现，负责解析实验描述并提供环境、模型、控制参数等访问入口。

描述模板的完整内容见 descriptionTemplate.tpl，这是 OPF 实验生成器（Experiment Generator）用来生成真实description.py的模板——所有$XXXXXXXX形式的 token 都会被替换为具体值。从模板源码可以提取一份完整的模型配置字典结构，这是配置 OPF 实验的核心蓝图：

顶层配置

数据聚合（Aggregation）参数

• __aggregationPeriod：聚合周期（由$AGGREGATION_PERIOD生成），是允许被 permutation 覆盖的参数；
• aggregationInfo：聚合规则。其值 schema 为{'periodUnit1': value1, ..., 'fields': [('fieldNameA', aggFuncNameA), ...]}。聚合时间单位支持[years months]（与其余单位互斥）或[weeks days hours minutes seconds milliseconds microseconds]的任意组合；字段聚合函数支持"first"、"last"、"mean"、"sum"。若省略aggregationInfo或所有周期单位值均为 0，则聚合被禁用。序列 id、Reset、Timestamp 字段若未在聚合字段中显式指定会被自动包含。

传感器与编码器参数

• sensorVerbosity：传感器诊断输出级别，0 为静默，≥1 有部分信息；
• sensorAutoReset：RecordSensor 自动生成 reset 的周期字典（键可为 days/hours/minutes/seconds/milliseconds/microseconds/weeks），None表示禁用；
• dsEncoderSchema：数据集编码器 schema，每个字段编码器字典必须包含fieldname（数据字段名）、type（编码器类型）以及其余编码器参数。模板还演示了用DeferredDictLookup做"延迟取值"的技巧——例如把自定义变量_dsEncoderFieldName2_N通过DeferredDictLookup('_dsEncoderFieldName2_N')注入n、w参数，从而允许子实验/permutation 覆盖单个编码器参数（见模板第 59-88 行的注释示例）。各类编码器的类型值与参数可参考 encoders 模块。

通用 CLA 区域参数

• claRegionNColumns：皮层区域列数（SP 与 TM 共用），模板默认 2048。

Spatial Pooler（SP）参数

Temporal Memory（TM）参数

SDRClassifier 参数

模板末尾的执行逻辑值得注意：先调用updateConfigFromSubConfig(config)让子实验覆盖基础配置；然后若predictAheadTime非空，则按int(round(aggregationDivide(predictAheadTime, __aggregationPeriod)))计算predictionSteps并回填到clSteps；最后调用applyValueGettersToContainer(config)解析所有延迟取值。这段"子实验覆盖 → 计算派生值 → 解析延迟取值"的三段式流程是 OPF 支持 swarming/permutation 的关键机制。

客户端（Clients）与命令行运行：Experiment Runner

Client 类

Clients 文档 定义了nupic.frameworks.opf.client.Client（src/nupic/frameworks/opf/client.py），它是 OPF 对外提供的一种客户端封装，供上层系统通过客户端对象驱动 OPF 工作。

runExperiment：执行单个实验

Experiment Runner 文档 是命令行形态的核心，对应源码 experiment_runner.py，该模块明确声明是"被命令行客户端 run_opf_experiment.py 调用的 API"。它暴露两个函数：

• runExperiment(args, model=None)：运行单个 OPF 实验。args是命令行参数列表，支持：

  • -c <CHECKPOINT>：只创建模型并按给定名称保存检查点，不运行；
  • --listCheckpoints：列出所有可用检查点；
  • --listTasks：列出 description.py 中的所有任务标签；
  • --load=<CHECKPOINT>：从检查点加载模型并运行；
  • --newSerialization：使用新的 capnproto 序列化；
  • --tasks：按给定任务标签顺序运行指定任务（默认运行 description.py 中所有任务）；
  • 完整选项可用--help查看。

  函数内部的核心调用链（从 import 语句可推断）：helpers负责加载实验描述 →ModelFactory创建模型 →OPFTaskDriver驱动任务执行 → 期间使用InferenceElement、matchPatterns、validateOpfJsonValue等工具。它还依赖全局常量g_defaultCheckpointExtension = ".nta"以及一份严格的私有命令行选项 JSON schema（g_parsedPrivateCommandLineOptionsSchema）来校验控制参数。

• initExperimentPrng()：初始化实验栈可能用到的伪随机数生成器，固定 seed = 42 分别作用于 Pythonrandom与numpy.random，以保证实验跨运行的可重复性。调用方若有自己的 PRNG 初始化逻辑，可跳过此函数。

main()是模块级入口：initLogging(verbose=True)初始化日志 →initExperimentPrng()固定随机种子 →runExperiment(sys.argv[1:])执行（experiment_runner.py）。因此命令行运行一个实验的最简方式即：

python scripts/run_opf_experiment.py <experiment_dir> [--tasks ...] [--load=<checkpoint>]

任务驱动与运行环境（Environment）：OPF 的执行引擎

Environment 文档 把 OPF 运行期拆成三块：

OPF Task Driver

OPFTaskDriver（src/nupic/frameworks/opf/opf_task_driver.py）负责把"任务"翻译成对模型的一轮轮迭代调用。它配套三种迭代阶段规格（IterationPhaseSpec），分别定义每一轮迭代的动作组合：

• IterationPhaseSpecLearnOnly：仅学习；
• IterationPhaseSpecInferOnly：仅推断；
• IterationPhaseSpecLearnAndInfer：学习与推断同时进行。

这三种规格正是"在线学习"的三种典型节奏：训练期可学习+推断，纯推断期则关闭学习，从而支撑实验设计中 learn/infer 交替的 phase 配置。

OPF Environment 与 OPF Basic Environment

• opf_environment提供PredictionLoggerIface：预测日志的抽象接口；
• opf_basic_environment（src/nupic/frameworks/opf/opf_basic_environment.py）则给出可直接使用的默认实现：
  • PredictionMetricsLoggerIface：预测指标日志接口；
  • DatasetReaderIface：数据集读取接口；
  • BasicPredictionMetricsLogger：基础指标日志实现；
  • BasicDatasetReader：基础数据集读取实现；
  • NonTemporalPredictionLogAdapter：针对非时序模型预测日志的适配器；
  • BasicPredictionLogger：基础预测日志实现。

这套"接口 + 基础实现 + 适配器"的结构意味着：接入新数据源或新日志格式时，只需实现对应 Iface 或替换 Adapter，不必改动模型与任务驱动。

预测指标（Metrics）：如何度量模型好坏

Metrics 文档 定义了 OPF 的指标体系，分三部分：

• 管理器：MetricsManager（src/nupic/frameworks/opf/prediction_metrics_manager.py）统一管理、累计、上报各项指标；
• 接口与规格：MetricsIface（指标抽象接口）、MetricSpec（指标的声明式规格，在 description.py 中通过它声明要计算的指标）、CustomErrorMetric（自定义误差指标）、AggregateMetric（聚合指标）；辅助函数getModule用于按名称动态获取指标模块；
• 内置指标族（位于 src/nupic/frameworks/opf/metrics.py）：

这组指标覆盖了回归（RMSE/AAE/MAPE）、概率（NLL）、分类（Accuracy/AUC）与多步预测（MultiStep）四大场景，基本可以无自定义代码地度量绝大多数实验。

结果对象与工具（Results & Utilities）

ModelResult 与 InferenceShifter

Results 文档 定义了两类结果相关类型：

• ModelResult（src/nupic/frameworks/opf/opf_utils.py）：单次模型运行产出的结果容器，携带推断值、原始输入、指标值等；
• InferenceShifter（src/nupic/data/inference_shifter.py）：推断移位器，用于把"提前多步"的预测结果与原始时间序列对齐——这是评估多步预测时必不可少的对齐工具。

工具集（Utilities）

Utils 文档 涵盖四类实用设施：

• Common Models：nupic.frameworks.opf.common_models.cluster_params（common_models/cluster_params.py，目录下另有 cluster_params.json）提供常用模型参数模板；
• Inference 枚举：InferenceType（推断类型，如 Nontemporal / Temporal / TemporalAnomaly）与InferenceElement（推断元素，如predictedField、anomalyScore、activeCells等），二者共同定义了模型"输出什么、以什么语义输出"；
• 输入结构：SensorInput（传感器输入，封装数据源信息）与ClassifierInput（分类器输入）；
• 辅助函数：
  • helpers.loadExperiment/helpers.loadExperimentDescriptionScriptFromDir/getExperimentDescriptionInterfaceFromModule：从实验目录加载description.py并还原出描述接口；
  • opf_utils.validateOpfJsonValue：按 JSON schema 校验 OPF 配置值；
  • opf_utils.initLogger：初始化模块日志；
  • opf_utils.matchPatterns：模式匹配工具（任务标签匹配等）。

异常体系（Exceptions）

Exceptions 文档 定义了 src/nupic/frameworks/opf/exceptions.py 中的三个异常类型：

• HTMPredictionModelException：HTMPredictionModel 的通用异常基类；
• HTMPredictionModelInvalidArgument：非法参数异常；
• HTMPredictionModelInvalidRangeError：非法范围异常（如anomalyAddLabel/anomalyRemoveLabels中 start/end 范围非法）。

使用建议：捕获异常时应优先捕获这两个派生异常以获得精确语义，最后兜底HTMPredictionModelException。

从描述到运行：OPF 的端到端数据流

综合上述模块，一次 OPF 实验的完整数据流可以概括为：

1. 声明：实验目录中放置description.py（由descriptionTemplate.tpl模板生成），声明model、inferenceType、dsEncoderSchema、SP/TM/classifier 参数、inferenceArgs（含predictedField）、metrics（用MetricSpec声明）与control（learn/infer phase）等；
2. 加载：runExperiment经由helpers.loadExperimentDescriptionScriptFromDir读取并解析 description；
3. 创建：ModelFactory.create(modelConfig)按model类型实例化模型，HTMPredictionModel内部通过nupic.engine.Network组装 Sensor → Encoder（MultiEncoder）→ SP → TM → SDRClassifierRegion 的网络（__createHTMNetwork返回NetworkInfo(net, statsCollectors)，见 htm_prediction_model.py）；
4. 驱动：OPFTaskDriver按IterationPhaseSpec*的节奏驱动模型逐迭代学习/推断；
5. 度量与产出：每次迭代的结果封装为ModelResult，由MetricsManager依据MetricSpec累计计算指标，预测日志经由BasicPredictionLogger落盘；多步预测结果如需对齐时序则用InferenceShifter；
6. 持久化：模型可随时以检查点（默认扩展名.nta，或 capnp 新序列化）保存，后续用--load或ModelFactory.loadFromCheckpoint恢复继续。

结语

OPF 是 nupic-legacy 中连接"底层 HTM 算法网络"与"上层业务预测"的胶水层：ModelFactory与HTMPredictionModel是它的门面，description.py模板是它的配置语言，experiment_runner与OPFTaskDriver是它的执行引擎，Metrics 与ModelResult是它的度量与输出。无论你是想通过scripts/run_opf_experiment.py跑通一个现成实验，还是想在自有系统中嵌入 HTM 在线预测能力，本文梳理的这套 API 面（docs/source/api/opf/）都能作为直接的地图。建议继续研读仓库中的配套材料：快速入门示例、OPF 指南、完整 OPF 示例 以及 run_opf_experiment.py，以实际代码巩固本文所述各模块的协作方式。

• 机器学习
• 人工智能