企业官网建设流程全解析

• 科学计算
• 数据分析

本文以 NumPy 仓库中的变更公告（doc/release/upcoming_changes/32015.deprecation.rst）为主线，系统梳理numpy.linalg.lapack_lite被弃用的来龙去脉：它是什么、为什么会被弃用、弃用在源码中如何落地，以及用户应如何平滑迁移到官方推荐的替代方案。读完本文，你将能准确识别受影响的代码、理解告警的触发机制，并掌握scipy.linalg.lapack/scipy.linalg.blas与numpy.show_config()的正确用法。

一、变更公告说了什么

该变更公告的核心内容可以概括为三点：

1. 被弃用的对象：import numpy.linalg.lapack_lite这一导入操作本身即被弃用；
2. 弃用理由：该模块是numpy.linalg的内部实现细节（internal implementation detail），从未被设计为公共 API；
3. 替代方案：需要 LAPACK 或 BLAS 例程的用户，应改用scipy.linalg.lapack或scipy.linalg.blas。

公告原文明确指出：The module is an internal implementation detail of `numpy.linalg` and was never intended as a public API.这意味着任何直接导入该模块的用户代码，都是在触碰 NumPy 的"私有内脏"，其行为、函数签名与存在性都不在 NumPy 的兼容性承诺范围内。

二、lapack_lite 到底是什么：从 f2c 源码到内建回退实现

要理解这次弃用，必须先弄清楚lapack_lite在 NumPy 中的地位。

构建与源码组成

在 numpy/linalg/lapack_lite/README.rst 中可以看到，numpy/linalg/f2c_*.c系列文件是 LAPACK 例程的f2c 转换版本（由 Fortran 源代码经f2c工具翻译为 C），服务于LinearAlgebra（即numpy.linalg）模块，并由lapack_lite模块包装。这些源码可通过 make_lite.py 从 LAPACK 源码树自动重新生成，仓库中使用的 LAPACK 版本为 3.2.2。

从 numpy/linalg/meson.build 的构建配置可以看清它的定位：

lapack_lite_sources = [] if not have_lapack lapack_lite_sources = [ 'lapack_lite/f2c.c', 'lapack_lite/f2c_c_lapack.c', 'lapack_lite/f2c_d_lapack.c', 'lapack_lite/f2c_s_lapack.c', 'lapack_lite/f2c_z_lapack.c', 'lapack_lite/f2c_blas.c', 'lapack_lite/f2c_config.c', 'lapack_lite/f2c_lapack.c', ] endif py.extension_module('lapack_lite', [ 'lapack_litemodule.c', python_xerbla_sources, lapack_lite_sources, ], ... )

关键点在于if not have_lapack：当系统没有可用的外部 LAPACK 库时，NumPy 才会把整套 f2c 翻译的 LAPACK/BLAS 实现编译进lapack_lite扩展模块。也就是说，lapack_lite本质上是"内建回退实现"——保证在没有外部 LAPACK 的环境里，numpy.linalg的核心线性代数功能（如lstsq、qr、svd等）依然可用。而_umath_linalg（numpy/linalg/umath_linalg.cpp）同样链接了这些源码，并用一把全局锁串行化对lapack_lite的调用。

暴露的 LAPACK/BLAS 例程

numpy/linalg/lapack_lite/wrapped_routines 列出了被包装的例程清单，覆盖单精度/双精度/复数（s/d/c/z 前缀）的 LAPACK 与 BLAS 操作：

此外还包含dcabs1等辅助函数，而xerbla（LAPACK 错误处理入口）在清单中被显式标注为IGNORE，由 python_xerbla.c 单独提供。

在 numpy/linalg/_linalg.py 的qr文档中还有一段佐证：lapack_lite中保存着一些支持raw模式（Householder 反射器直接相乘）的例程，"No routines using the 'raw' return are currently exposed by numpy, but some are available in lapack_lite and just await the necessary work"——这直接印证了该模块从未面向用户公开、仅是内部待用资源的事实。

三、弃用是如何落地的：源码级实现细节

本次弃用并非仅仅停留在文档层面，在 numpy/linalg/lapack_litemodule.c 的模块初始化函数lapack_lite_exec中，有完整的运行时实现：

if (PyErr_WarnEx(PyExc_DeprecationWarning, "The numpy.linalg.lapack_lite module is deprecated and will be " "removed in a future release. It is an internal implementation " "detail of numpy.linalg. Users that need LAPACK or BLAS routines " "should use scipy.linalg.lapack or scipy.linalg.blas instead. " "For users checking BLAS/LAPACK library paths or configuration, " "use numpy.show_config() instead.", 2) < 0) { return -1; }

从中可以提取几个关键实现事实：

1. 导入即告警：只要import numpy.linalg.lapack_lite成功执行，就会触发一次DeprecationWarning，无需调用任何函数；
2. 告警文案完整：不仅给出替代方案（scipy.linalg.lapack/scipy.linalg.blas），还额外提示了配置检查场景应改用numpy.show_config()；
3. stacklevel=2：告警的栈层级指向调用者代码位置，便于定位出问题的导入语句；
4. 模块级约束：lapack_lite_exec中还有一个module_loaded检查，同一进程内该模块只允许被加载一次，否则抛出ImportError（"cannot load module more than once per process"）；
5. 线程/GIL 相关：模块在 Python 3.13+ 下声明Py_MOD_GIL_NOT_SUPPORTED（支持无 GIL 运行），而_umath_linalg侧则用全局锁（numpy/linalg/umath_linalg.cpp）串行化对lapack_lite的调用。

该模块还通过每个模块实例的状态（lapack_lite_state）维护了LapackError异常类（numpy.linalg.lapack_lite.LapackError）与_ilp64标志（根据构建时是否定义了HAVE_BLAS_ILP64决定真假，用于标识 64 位整数 LAPACK 接口）。

类型桩的同步标记

与 C 扩展同步，numpy/linalg/lapack_lite.pyi 类型桩中的每个函数（dgelsd、zgelsd、dgeqrf、zgeqrf、dorgqr、zungqr等）都被@deprecated装饰器标记，并携带与 C 侧一致的弃用文案。这意味着静态类型检查工具（如 mypy 配合warn_unused_ignores或 stubtest）也能提前向你报告这些 API 的弃用状态。从桩签名可以看到，这些函数直接对应 Fortran LAPACK 的原始参数约定（m/n/nrhs/lda/ldb/rank/lwork/info等），调用方需要自行管理工作区数组（work/iwork/rwork），属于典型的"裸 LAPACK"接口风格——这正是它不适合作为公共 API 的又一个原因。

四、为什么它"从未被设计为公共 API"

综合上述源码证据，可以从三个层面理解这次弃用的合理性：

• 接口风格是 Fortran 裸绑定：lapack_lite的调用约定与 LAPACK 的 Fortran 接口一一对应，参数包含lda、lwork、info等底层细节，与numpy.linalg面向用户的封装风格（如np.linalg.svd、np.linalg.qr）完全不同，需要用户手工处理工作数组与内存布局；
• 依赖未公开的特性：模块只在特定构建条件（无外部 LAPACK）下才包含完整的 f2c 实现，其可用例程集合、_ilp64标志等都随构建配置变化，公共 API 不应依赖这类构建时不确定性；
• 存在演进约束：如_linalg.py所述，其中部分raw模式的例程"await the necessary work"，模块的形态本身仍在演进中，将其固定为公共契约会阻碍 NumPy 内部重构。

因此，弃用的本质是收回一个被误用的内部实现，而不是移除任何公开承诺的能力——numpy.linalg面向用户的接口完全不受影响。

五、迁移路径：官方推荐的替代方案

根据公告与运行时告警文案，官方给出了两条明确的迁移路径。

场景一：需要 LAPACK/BLAS 例程

直接改用 SciPy 的高层封装，替换表如下：

迁移示例：

# 弃用前（直接触碰内部模块） import numpy.linalg.lapack_lite as ll import numpy as np a = np.array([[3.0, 1.0], [1.0, 2.0]]) # ... # 推荐做法：使用 scipy 的公开封装 from scipy.linalg import lapack # 例如求最小二乘解（对应 dgelsd） a = np.array([[3.0, 1.0], [1.0, 2.0]]) b = np.array([1.0, 2.0]) x, _, _, _ = lapack.dgelsd(a, b) # 无需自行管理 lwork/iwork 等工作数组

SciPy 的lapack/blas子模块提供了与 Fortran 例程对应的封装，同时自动处理了工作区大小计算与数组布局检查，调用体验和安全性与裸的lapack_lite相比有本质提升。

场景二：检查 BLAS/LAPACK 库路径或配置

如果你此前依赖lapack_lite（或其相关 API）来探测 BLAS/LAPACK 的链接路径与构建配置，官方推荐的替代是：

import numpy numpy.show_config()

numpy.show_config()会输出当前构建所链接的 BLAS、LAPACK、OpenBLAS 等库的路径、版本与编译信息，这是检查底层线性代数库配置的受支持方式，替代对_ilp64等内部标志的直接依赖。

需要处理告警的临时做法

如果你暂时无法立即迁移（例如被第三方代码间接导入），可以通过标准warnings机制临时过滤告警，但这仅建议作为过渡手段：

import warnings with warnings.catch_warnings(): warnings.filterwarnings( "ignore", message="The numpy.linalg.lapack_lite module is deprecated", category=DeprecationWarning, ) import numpy.linalg.lapack_lite # 仅限过渡期

注意：该模块最终会在未来某个版本中被彻底移除，过滤告警并不能阻止移除后的ImportError。

六、测试与兼容性验证

NumPy 自身的测试已经为这次弃用做了示范。在 numpy/linalg/tests/test_linalg.py 中：

try: with warnings.catch_warnings(): warnings.filterwarnings( "ignore", message="The numpy.linalg.lapack_lite module is deprecated", category=DeprecationWarning, ) import numpy.linalg.lapack_lite except ImportError: # May be broken when numpy was built without BLAS/LAPACK present # If so, ensure we don't break the whole test suite - the `lapack_lite` # submodule should be removed, it's only used in two tests in this file. pass

这段测试代码同时印证了两个事实：

1. 即使 NumPy 内部测试也需要先抑制DeprecationWarning才能导入该模块；
2. 源码注释明确写道the lapack_lite submodule should be removed, it's only used in two tests in this file——即 NumPy 自身也仅在少数测试中依赖它（例如通过np.linalg.lapack_lite.xerbla()和dorgqr验证xerbla错误处理链接是否生效，见 test_linalg.py），且这些用例已为移除做好了降级准备。

七、如何自查你的代码是否受影响

在升级 NumPy 后，如果发现测试日志中出现如下告警：

DeprecationWarning: The numpy.linalg.lapack_lite module is deprecated and will be removed in a future release...

请按以下步骤排查：

1. 定位导入点：在仓库中全局搜索lapack_lite与import numpy.linalg，找出所有直接导入该模块的位置；
2. 判断来源：如果是你自己的代码直接导入，立即按第五节方案迁移；如果来自第三方依赖，检查其是否有更新版本或 issue 说明；
3. 确认用途：区分"调用 LAPACK 例程"（→scipy.linalg.lapack/scipy.linalg.blas）与"检查 BLAS/LAPACK 配置"（→numpy.show_config()）两种场景，分别迁移；
4. 验证迁移结果：在 CI 或本地测试中加入-W error::DeprecationWarning（或使用pytest -W error）将告警升级为错误，确保没有遗漏的导入点。

八、小结

numpy.linalg.lapack_lite的弃用是一次典型的"内部实现收归"：它由 f2c 翻译的 LAPACK 3.2.2 源码构建而来，作为无外部 LAPACK 环境下的内建回退，服务于numpy.linalg的底层实现，其 Fortran 裸绑定式的接口风格决定了它从未适合成为公共 API。本次弃用在运行时（DeprecationWarning）、类型桩（@deprecated）与测试（告警抑制 + 移除预案）三个层面同步落地，为用户留出了充分的迁移窗口。对于普通用户，numpy.linalg的功能不受任何影响；对于少数直接依赖该模块的代码，scipy.linalg.lapack/scipy.linalg.blas与numpy.show_config()就是官方给出的明确出路。

• 科学计算
• 数据分析