在 macOS 上 5 分钟编译并加载 SQLite-Vec 扩展搞定 3 个高频报错【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vec你在终端敲下.load ./sqlite-vec结果等来的是一句unable to open shared library。别慌这是 macOS 上 SQLite-Vec 扩展加载最常见的卡点你想加载的那个文件很可能根本不存在或者路径没被找到。这篇文章带你从零把 sqlite-vec 编译成 macOS 能用的vec0.dylib配好DYLD_LIBRARY_PATH再分别用 sqlite3 命令行和 Python 把它加载起来最后对 3 个高频报错各给一份直接能用的处方。先确认工具链编译器和 Homebrew 装好了吗这一步最容易翻车但只有两条命令xcode-select -p它用来确认 Xcode 命令行工具是否已安装正常会打印出/Library/Developer/CommandLineTools。如果提示未安装执行下面这条来装上首次会弹窗点安装等它跑完即可xcode-select --installHomebrew 用来后面解决 SQLite 版本兼容问题先确认一下brew --version能打印出版本号例如Homebrew 4.x就说明环境齐了没有的话先按 Homebrew 官网的安装脚本装好再继续。克隆源码一条 make 命令编出 vec0.dylib先克隆仓库并进入目录scripts/vendor.sh会把一份最新 SQLite amalgamation 下载到vendor/供编译时引用头文件详见 scripts/vendor.shgit clone https://gitcode.com/GitHub_Trending/sq/sqlite-vec cd sqlite-vec ./scripts/vendor.sh克隆成功后你会进入sqlite-vec/目录vendor.sh跑完时会在当前目录多出一个vendor/文件夹。然后执行编译——注意用make loadable而不是裸的make它只构建可加载扩展比默认全量构建快得多规则定义在 Makefile 里make loadable成功后终端最后会有一行dist/vec0.dylib相关的输出项目根目录下多出一个dist/目录。这个dist/vec0.dylib就是你要加载的扩展库本体。file 命令的输出怎么看用file检查这个 dylib 是不是合格的 macOS 动态库file dist/vec0.dylib正常输出形如dist/vec0.dylib: Mach-O 64-bit dynamically linked shared library arm64只要看到Mach-O 64-bit dynamically linked shared library后面跟arm64Apple 芯片或x86_64Intel 芯片且与你的机器架构一致就说明编译成功。把 dylib 目录塞进 DYLD_LIBRARY_PATHMacOS 用DYLD_LIBRARY_PATH来提示系统去哪里找动态库。执行下面这条把dist/目录加进去注意保留原有值用:追加export DYLD_LIBRARY_PATH$DYLD_LIBRARY_PATH:$(pwd)/dist立即验证一下是否生效echo $DYLD_LIBRARY_PATH输出末尾应包含.../sqlite-vec/dist。想让它每次开终端都生效把这条export追加到~/.zshrc即可macOS 默认 shell 是 zsh。坦白说sqlite3的.load主要靠你传入的路径找文件这个变量更像是给你自己程序动态链接扩展库时的保险绳——但配上不亏。在 sqlite3 里用 .load 加载扩展先切到项目目录再进 sqlite3这样相对路径好写cd sqlite-vec sqlite3 :memory: .load dist/vec0 select vec_version();这条命令在内存数据库上加载扩展并查询版本号。成功的话你会看到类似0.1.10-alpha.4的一行输出——版本号对得上说明 SQLite-Vec 扩展已经在工作了。在 Python 里用 load_extension 自动加载如果你的目标是把向量搜索接进应用把加载动作写进代码里每次启动自动完成import sqlite3 db sqlite3.connect(:memory:) db.enable_load_extension(True) db.load_extension(dist/vec0) # 注意相对当前工作目录 db.enable_load_extension(False) print(db.execute(select vec_version()).fetchone())注意load_extension传的是dist/vec0而不是dist/vec0.dylib——仓库的测试如 tests/conftest.py就是这么写的SQLite 会自动补全后缀。脚本要在项目根目录下运行或者干脆传绝对路径输出同样是版本号元组。报错一unable to open shared library为什么报SQLite 按你给的路径找不到文件。绝大多数情况是路径写错了文件在dist/里不在当前目录或者当前目录不对。两条命令定位ls -l dist/vec0.dylib # 文件到底存不存在 pwd # 我到底在哪个目录下一条命令修复直接用绝对路径绕开一切相对路径歧义sqlite3 :memory: .load $(pwd)/dist/vec0 select vec_version();能打印版本号这个坑就过去了。报错二SQLITE_CANTOPEN 或 no such function: vec_version为什么报SQLITE_CANTOPEN是 SQLite 的无法打开文件错误码本质和上一条同源——Python 里load_extension找不到扩展文件就抛它而no such function: vec_version则是扩展压根没加载成功SQL 里的向量函数自然不存在。两条命令定位ls -l dist/vec0.dylib # 确认扩展文件存在 file dist/vec0.dylib # 确认架构匹配arm64/x86_64 要和你的 Mac 一致如果file显示的架构和你的机器不一致比如在 arm64 机器上编出了 x86_64 的库删掉dist/重新make loadable即可。一条命令修复回到项目根目录用最短相对路径重新加载cd sqlite-vec python3 -c import sqlite3; dbsqlite3.connect(:memory:); db.enable_load_extension(True); db.load_extension(dist/vec0); print(db.execute(select vec_version()).fetchone())打印出版本号即修复成功。报错三系统自带的 SQLite 太旧为什么报macOS 自带的 sqlite3 版本往往落后不少可能无法加载较新的扩展或部分新语法如 KNN 查询的LIMIT形式不支持。先看看你的版本sqlite3 --version如果版本号明显偏旧比如还停在 3.3x 甚至更早就是它的问题了。一条命令修复用 Homebrew 装一个新版 SQLite并把它放到 PATH 前面brew install sqlite3 export PATH/opt/homebrew/bin:$PATHIntel 机器对应的是/usr/local/bin。之后sqlite3 --version应显示 3.45 的新版本。若你还要自己编译扩展可以让 Makefile 直接链接 Homebrew 的 SQLiteMakefile 内置了这个开关Apple 芯片路径make loadable USE_BREW_SQLITE1重新加载验证版本号版本兼容问题即关闭。更多安装途径可参考 site/getting-started/installation.md编译细节见 site/compiling.md。✅ 下一步可以做什么跑一条真正的 KNN 查询验证向量搜索端到端可用写法见 site/features/knn.mdPython 项目里其实也可以不自己编译pip install sqlite-vec会直接带预编译扩展编译流程留给需要定制的场景每次更新源码后重跑make loadable保持扩展最新想深入vec0虚拟表的高级用法余弦距离、分区等翻一遍 site/features/vec0.md【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 macOS 上 5 分钟编译并加载 SQLite-Vec 扩展：搞定 3 个高频报错
在 macOS 上 5 分钟编译并加载 SQLite-Vec 扩展搞定 3 个高频报错【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vec你在终端敲下.load ./sqlite-vec结果等来的是一句unable to open shared library。别慌这是 macOS 上 SQLite-Vec 扩展加载最常见的卡点你想加载的那个文件很可能根本不存在或者路径没被找到。这篇文章带你从零把 sqlite-vec 编译成 macOS 能用的vec0.dylib配好DYLD_LIBRARY_PATH再分别用 sqlite3 命令行和 Python 把它加载起来最后对 3 个高频报错各给一份直接能用的处方。先确认工具链编译器和 Homebrew 装好了吗这一步最容易翻车但只有两条命令xcode-select -p它用来确认 Xcode 命令行工具是否已安装正常会打印出/Library/Developer/CommandLineTools。如果提示未安装执行下面这条来装上首次会弹窗点安装等它跑完即可xcode-select --installHomebrew 用来后面解决 SQLite 版本兼容问题先确认一下brew --version能打印出版本号例如Homebrew 4.x就说明环境齐了没有的话先按 Homebrew 官网的安装脚本装好再继续。克隆源码一条 make 命令编出 vec0.dylib先克隆仓库并进入目录scripts/vendor.sh会把一份最新 SQLite amalgamation 下载到vendor/供编译时引用头文件详见 scripts/vendor.shgit clone https://gitcode.com/GitHub_Trending/sq/sqlite-vec cd sqlite-vec ./scripts/vendor.sh克隆成功后你会进入sqlite-vec/目录vendor.sh跑完时会在当前目录多出一个vendor/文件夹。然后执行编译——注意用make loadable而不是裸的make它只构建可加载扩展比默认全量构建快得多规则定义在 Makefile 里make loadable成功后终端最后会有一行dist/vec0.dylib相关的输出项目根目录下多出一个dist/目录。这个dist/vec0.dylib就是你要加载的扩展库本体。file 命令的输出怎么看用file检查这个 dylib 是不是合格的 macOS 动态库file dist/vec0.dylib正常输出形如dist/vec0.dylib: Mach-O 64-bit dynamically linked shared library arm64只要看到Mach-O 64-bit dynamically linked shared library后面跟arm64Apple 芯片或x86_64Intel 芯片且与你的机器架构一致就说明编译成功。把 dylib 目录塞进 DYLD_LIBRARY_PATHMacOS 用DYLD_LIBRARY_PATH来提示系统去哪里找动态库。执行下面这条把dist/目录加进去注意保留原有值用:追加export DYLD_LIBRARY_PATH$DYLD_LIBRARY_PATH:$(pwd)/dist立即验证一下是否生效echo $DYLD_LIBRARY_PATH输出末尾应包含.../sqlite-vec/dist。想让它每次开终端都生效把这条export追加到~/.zshrc即可macOS 默认 shell 是 zsh。坦白说sqlite3的.load主要靠你传入的路径找文件这个变量更像是给你自己程序动态链接扩展库时的保险绳——但配上不亏。在 sqlite3 里用 .load 加载扩展先切到项目目录再进 sqlite3这样相对路径好写cd sqlite-vec sqlite3 :memory: .load dist/vec0 select vec_version();这条命令在内存数据库上加载扩展并查询版本号。成功的话你会看到类似0.1.10-alpha.4的一行输出——版本号对得上说明 SQLite-Vec 扩展已经在工作了。在 Python 里用 load_extension 自动加载如果你的目标是把向量搜索接进应用把加载动作写进代码里每次启动自动完成import sqlite3 db sqlite3.connect(:memory:) db.enable_load_extension(True) db.load_extension(dist/vec0) # 注意相对当前工作目录 db.enable_load_extension(False) print(db.execute(select vec_version()).fetchone())注意load_extension传的是dist/vec0而不是dist/vec0.dylib——仓库的测试如 tests/conftest.py就是这么写的SQLite 会自动补全后缀。脚本要在项目根目录下运行或者干脆传绝对路径输出同样是版本号元组。报错一unable to open shared library为什么报SQLite 按你给的路径找不到文件。绝大多数情况是路径写错了文件在dist/里不在当前目录或者当前目录不对。两条命令定位ls -l dist/vec0.dylib # 文件到底存不存在 pwd # 我到底在哪个目录下一条命令修复直接用绝对路径绕开一切相对路径歧义sqlite3 :memory: .load $(pwd)/dist/vec0 select vec_version();能打印版本号这个坑就过去了。报错二SQLITE_CANTOPEN 或 no such function: vec_version为什么报SQLITE_CANTOPEN是 SQLite 的无法打开文件错误码本质和上一条同源——Python 里load_extension找不到扩展文件就抛它而no such function: vec_version则是扩展压根没加载成功SQL 里的向量函数自然不存在。两条命令定位ls -l dist/vec0.dylib # 确认扩展文件存在 file dist/vec0.dylib # 确认架构匹配arm64/x86_64 要和你的 Mac 一致如果file显示的架构和你的机器不一致比如在 arm64 机器上编出了 x86_64 的库删掉dist/重新make loadable即可。一条命令修复回到项目根目录用最短相对路径重新加载cd sqlite-vec python3 -c import sqlite3; dbsqlite3.connect(:memory:); db.enable_load_extension(True); db.load_extension(dist/vec0); print(db.execute(select vec_version()).fetchone())打印出版本号即修复成功。报错三系统自带的 SQLite 太旧为什么报macOS 自带的 sqlite3 版本往往落后不少可能无法加载较新的扩展或部分新语法如 KNN 查询的LIMIT形式不支持。先看看你的版本sqlite3 --version如果版本号明显偏旧比如还停在 3.3x 甚至更早就是它的问题了。一条命令修复用 Homebrew 装一个新版 SQLite并把它放到 PATH 前面brew install sqlite3 export PATH/opt/homebrew/bin:$PATHIntel 机器对应的是/usr/local/bin。之后sqlite3 --version应显示 3.45 的新版本。若你还要自己编译扩展可以让 Makefile 直接链接 Homebrew 的 SQLiteMakefile 内置了这个开关Apple 芯片路径make loadable USE_BREW_SQLITE1重新加载验证版本号版本兼容问题即关闭。更多安装途径可参考 site/getting-started/installation.md编译细节见 site/compiling.md。✅ 下一步可以做什么跑一条真正的 KNN 查询验证向量搜索端到端可用写法见 site/features/knn.mdPython 项目里其实也可以不自己编译pip install sqlite-vec会直接带预编译扩展编译流程留给需要定制的场景每次更新源码后重跑make loadable保持扩展最新想深入vec0虚拟表的高级用法余弦距离、分区等翻一遍 site/features/vec0.md【免费下载链接】sqlite-vecA vector search SQLite extension that runs anywhere!项目地址: https://gitcode.com/GitHub_Trending/sq/sqlite-vec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考