我先说结论。txtai 是个 all-in-one 的 AI 框架，把向量检索、RAG、LLM 编排塞进一个 Python 库。它的核心是 embeddings 数据库，按 README 的原话，是稀疏向量索引、稠密向量索引、图网络、关系数据库四样东西的并集。这一句我核过原文。它最吸引我的地方，是把别人要拼三四个库才能搭起来的东西，一个 pip install 全给。这篇记我装它、跑语义搜索、撞上 macOS 的 MPS 崩溃再绕过去。

装它花了我一轮时间

装的过程不顺利。第一遍 uv pip install txtai，默认 PyPI 源卡了十二分钟，torch 那个 132MB 的包反复超时。这跟 11-12 那轮 pydantic-ai 一模一样，网络对 PyPI 的下载就是不稳。我换清华镜像，加 UV_HTTP_TIMEOUT=120，几分钟装完。装出来 txtai 9.14.0，torch 2.15.0。这两个版本号我用 importlib.metadata 打出来的，不是猜的。

import txtai

embeddings = txtai.Embeddings()
embeddings.index(["Correct", "Not what we hoped"])
embeddings.search("positive", 1)

这段是 README 的 Getting started，我抄了结构，改了自己的写法。跑之前，我以为装完就能用。结果不是。

默认配置跑不起来

第一关是缺依赖。Embeddings() 默认用 sentence-transformers 的 all-MiniLM-L6-v2 做编码器，但基础安装不带 sentence-transformers。import 那一下直接 ModuleNotFoundError: No module named 'sentence_transformers'。我补装了一个，版本 sentence-transformers 6.3.0。

第二关更狠。补完再跑，模型权重 103 个分片下完了，前向一算，直接崩。报错原文是 NSInvalidArgumentException: -[MPSNDArray arrayViewWithShape:strides:]: unrecognized selector。这是 torch 在 macOS 上走 Metal 后端的 bug。txtai 默认配置里 gpu 是 True，在 arm64 mac 上它选了 mps，然后撞上这个坑。这个报错我一个字没改，就是它崩出来那行。

绕过去就一行

绕过去很简单。把 gpu 关掉，强制走 CPU。

embeddings = txtai.Embeddings({"gpu": False})

再跑，通了。我喂进去两句话，搜 positive，返回 [(0, 0.2986202836036682)]，指向第 0 条 Correct。搜 bad，返回 [(1, 0.27133703231811523)]，指向第 1 条 Not what we hoped。这串数字是本机实际跑出来的，不是我抄 README。看这两个结果。它没做关键词匹配，positive 是靠语义命中 Correct。0.2986 这个分数，跟 README 里给的 [(0, 0.29862046241760254)] 几乎一致，说明我复现对了。

这里有个判断。mac 上用 txtai，第一件事不是写索引，是先把 gpu 关成 False。这样省掉的就是我这一轮撞墙的时间。torch 的 MPS 后端在 arm64 mac 上跑这种小句子模型，收益很小，风险很大。关掉它不亏。

一个库装下四样

回到它值不值得。txtai 的卖点是把四样东西塞进一个库：向量检索、图网络、关系数据库、LLM 工作流。别人要拼 chroma 加 neo4j 加 langchain，它一个 pip install 全给。

四样东西不是并列的，是有主次。向量检索是地基，稠密向量管语义，稀疏向量管关键词，两套索引叠在一起，召回比单套高。图网络在上面跑话题聚类和网络分析。关系库存结构化字段，SQL 直接查。LLM 工作流是顶层，把前面的检索结果拼进 prompt。这套分层我读了架构图才看明白，之前以为它就是个向量库。README 里还有一句我记下来了，它说能跑 micromodel 也能跑大 LLM，低占用起步，按需往上加依赖。这个渐进式的设计，比一上来就 torch 全家桶要友好。

实际怎么用，README 给了两种形态。一种是嵌入式，像上面那样在 Python 里直接 index 和 search，适合单机脚本。另一种是起 API，写个 app.yml 指定模型，然后 CONFIG=app.yml uvicorn "txtai.api:app" 起服务，用 curl 搜。第二种适合要给别的语言用，它有 JavaScript、Java、Rust、Go 四个绑定。

# app.yml
embeddings:
    path: sentence-transformers/all-MiniLM-L6-v2

CONFIG=app.yml uvicorn "txtai.api:app"
curl -X GET "http://localhost:8000/search?query=positive"

agent 这块它也没落下。txtai 的 agent 建在 HuggingFace 的 smolagents 框架上，支持它支持的所有 LLM，还支持 agents.md 和 skill.md 这两种提示文件规范。所以它不只是个向量库，是条从向量到 agent 的完整链路。

还有一个点我差点漏了。它是本地优先的。数据不用送出去，模型也在本机跑，隐私敏感的检索场景，这个比托管向量库强。README 里那句 run local 不是空话，我这次全程没连任何外部 API 就跑通了。

给个分界

我的判断。你要一个轻量、单机、能离线跑的检索加 RAG 底座，txtai 值得上，尤其它把图检索和关系库也纳进来，省得拼。你要的是生产级、高并发、分布式的向量服务，那 milvus 这类专职向量库更对口。txtai 的强项在集成度，不在吞吐。

一句话。txtai 的定位是 all-in-one，代价是你得接受它的默认模型生态，以及在 mac 上要先关 MPS 这个坑。这个坑我已经替你踩过一遍了，照抄就能省掉。