[Bug] 无法创建知识库，报错"name 'SuperKMeans' is not defined"

[jin6yang]

What happened / 发生了什么

无法创建知识库，报错创建知识库失败: name 'SuperKMeans' is not defined

Reproduce / 如何复现？

配置好正确的嵌入模型填好相关信息后，创建知识库，即可稳定复现

AstrBot version, deployment method (e.g., Windows Docker Desktop deployment), provider used, and messaging platform used. / AstrBot 版本、部署方式（如 Windows Docker Desktop 部署）、使用的提供商、使用的消息平台适配器

4.26.7 Desktop

OS

Windows

Logs / 报错日志

[2026-07-26 14:16:34.704] [Core]
[ERRO]
[v4.26.7] [knowledge_base.kb_mgr:140]: 创建知识库失败
Traceback (most recent call last):
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_mgr.py", line 132, in create_kb
    await kb_helper.initialize()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 145, in initialize
    await self._ensure_vec_db()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 187, in _ensure_vec_db
    vec_db = FaissVecDB(
             ^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\vec_db.py", line 29, in __init__
    self.embedding_storage = EmbeddingStorage(
                             ^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\embedding_storage.py", line 9, in __init__
    import faiss
  File "D:\Application\AstrBot\backend\python\Lib\site-packages\faiss\__init__.py", line 127, in <module>
    class_wrappers.handle_SuperKMeans(SuperKMeans)
                                      ^^^^^^^^^^^
NameError: name 'SuperKMeans' is not defined
[2026-07-26 14:16:34.745] [Core]
[ERRO]
[v4.26.7] [api.knowledge_bases:67]: 创建知识库失败: name 'SuperKMeans' is not defined
Traceback (most recent call last):
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\api\knowledge_bases.py", line 59, in _run
    result = await run_maybe_async(operation)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\async_utils.py", line 20, in run_maybe_async
    return await resolve_maybe_awaitable(result)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\async_utils.py", line 12, in resolve_maybe_awaitable
    value = await cast(Awaitable[T], value)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\services\knowledge_base_service.py", line 354, in create_kb
    kb_helper = await kb_manager.create_kb(
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_mgr.py", line 132, in create_kb
    await kb_helper.initialize()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 145, in initialize
    await self._ensure_vec_db()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 187, in _ensure_vec_db
    vec_db = FaissVecDB(
             ^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\vec_db.py", line 29, in __init__
    self.embedding_storage = EmbeddingStorage(
                             ^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\embedding_storage.py", line 9, in __init__
    import faiss
  File "D:\Application\AstrBot\backend\python\Lib\site-packages\faiss\__init__.py", line 127, in <module>
    class_wrappers.handle_SuperKMeans(SuperKMeans)
                                      ^^^^^^^^^^^
NameError: name 'SuperKMeans' is not defined[2026-07-26 14:16:34.704] [Core]
[ERRO]
[v4.26.7] [knowledge_base.kb_mgr:140]: 创建知识库失败
Traceback (most recent call last):
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_mgr.py", line 132, in create_kb
    await kb_helper.initialize()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 145, in initialize
    await self._ensure_vec_db()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 187, in _ensure_vec_db
    vec_db = FaissVecDB(
             ^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\vec_db.py", line 29, in __init__
    self.embedding_storage = EmbeddingStorage(
                             ^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\embedding_storage.py", line 9, in __init__
    import faiss
  File "D:\Application\AstrBot\backend\python\Lib\site-packages\faiss\__init__.py", line 127, in <module>
    class_wrappers.handle_SuperKMeans(SuperKMeans)
                                      ^^^^^^^^^^^
NameError: name 'SuperKMeans' is not defined
[2026-07-26 14:16:34.745] [Core]
[ERRO]
[v4.26.7] [api.knowledge_bases:67]: 创建知识库失败: name 'SuperKMeans' is not defined
Traceback (most recent call last):
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\api\knowledge_bases.py", line 59, in _run
    result = await run_maybe_async(operation)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\async_utils.py", line 20, in run_maybe_async
    return await resolve_maybe_awaitable(result)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\async_utils.py", line 12, in resolve_maybe_awaitable
    value = await cast(Awaitable[T], value)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\dashboard\services\knowledge_base_service.py", line 354, in create_kb
    kb_helper = await kb_manager.create_kb(
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_mgr.py", line 132, in create_kb
    await kb_helper.initialize()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 145, in initialize
    await self._ensure_vec_db()
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\knowledge_base\kb_helper.py", line 187, in _ensure_vec_db
    vec_db = FaissVecDB(
             ^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\vec_db.py", line 29, in __init__
    self.embedding_storage = EmbeddingStorage(
                             ^^^^^^^^^^^^^^^^^
  File "\\?\D:\Application\AstrBot\backend\app\astrbot\core\db\vec_db\faiss_impl\embedding_storage.py", line 9, in __init__
    import faiss
  File "D:\Application\AstrBot\backend\python\Lib\site-packages\faiss\__init__.py", line 127, in <module>
    class_wrappers.handle_SuperKMeans(SuperKMeans)
                                      ^^^^^^^^^^^
NameError: name 'SuperKMeans' is not defined

Are you willing to submit a PR? / 你愿意提交 PR 吗？

• Yes!

Code of Conduct

• I have read and agree to abide by the project's Code of Conduct。

[dosubot]

这个错误是 faiss-cpu 包本身的导入问题，不是 AstrBot 的代码 bug。SuperKMeans 是 faiss-cpu 1.14.2 引入的新特性 [1]，在 Windows Desktop 部署中可能因 Python 绑定不完整导致导入失败。

建议的解决方案：

方案一（推荐）：降级到稳定版本

AstrBot 维护者此前也建议受影响的用户使用 faiss-cpu==1.13.2 [2]：

pip install faiss-cpu==1.13.2

方案二：清理后重新安装 1.14.3

pip uninstall faiss-cpu -y
pip install faiss-cpu==1.14.3 --no-cache-dir

另外，如果你的 Windows 用户名或安装路径包含中文等非 ASCII 字符，也可能导致 FAISS 加载失败，建议将 AstrBot 安装在纯英文路径下 [3]。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[Solaris-star]

当前 main 的 pyproject.toml 已通过 #8837 将基线提高到 faiss-cpu>=1.14.3，因此这里不应再次做同一版本升级。请在 Desktop 内嵌 Python 中执行以下不导入 faiss 的命令并贴出结果，用于确认实际打包 wheel：python -c "from importlib.metadata import version; import platform; print(version(\"faiss-cpu\"), platform.machine(), platform.python_version())"。若 Desktop 4.26.7 仍打包了 1.14.2，修复点在 Desktop 构建锁定/缓存；若实际为 1.14.3，则需要按该 Windows wheel 的导出符号问题继续定位。

[he-yufeng]

Traced this one down: SuperKMeans does not exist anywhere in AstrBot's own code, current master or the v4.26.7 tag itself (git grep across both trees comes back empty), and the repo's faiss dependency is only used through FaissVecDB. So the NameError is not raised by AstrBot code.

What it matches instead: a broken faiss installation. In faiss's own package, faiss/init.py runs class_wrappers.handle_SuperKMeans(SuperKMeans) at import time, and that line raises exactly "name 'SuperKMeans' is not defined" when the compiled swigfaiss module is missing that symbol (a mismatched or partial faiss wheel, typically after a pip mix between variants). The chain fits: create_kb -> kb_helper.initialize() -> FaissVecDB import -> faiss import fails.

Could you paste the bottom frames of the traceback (the last two or three lines above the NameError)? That will confirm whether it dies inside faiss/init.py. If it does, the immediate fix on your side is reinstalling the vector store dependency cleanly (pip install --force-reinstall faiss-cpu, or repair the Desktop environment if you installed via the bundled installer).

Either way, AstrBot could be kinder here: a NameError bubbling out of KB creation gives no hint that the vector backend is the broken piece. Wrapping the faiss import failure into a clear "faiss backend failed to initialize, check your faiss install" would save the next person the same hunt.