Weaviate 本地 Docker 部署与向量检索入门
Weaviate 是一个开源的向量数据库，核心用途是把文本、图片等数据转成向量后做相似度检索。
对新手来说，最省事的起步方式是用 Docker 拉起单节点服务，再通过 HTTP 接口完成建库、导入和查询。
下面按实际落地顺序讲清楚每一步做什么、在哪里看结果。
跑起来之前先确认两件事
Weaviate 单节点模式对机器要求不高，但需要满足两个前提：
- 已安装 Docker，执行
docker version能看到 Client 和 Server 信息。 - 宿主机至少留出 2GB 内存，因为向量化模块和索引会占用额外内存。
如果服务器开着防火墙，需要放行 8080（REST/GraphQL 接口）和 50051（gRPC 接口）。
只在本机测试可以跳过这步。
用 Docker 启动单节点 Weaviate
先建一个工作目录，把数据卷挂载到宿主机，避免容器删除后数据丢失：
mkdir -p /opt/weaviate/data
cd /opt/weaviate然后启动容器。
下面这条命令启用了 text2vec-transformers 模块，它会自动下载向量化模型，第一次启动会慢一些：
docker run -d \
--name weaviate \
-p 8080:8080 \
-p 50051:50051 \
-v /opt/weaviate/data:/var/lib/weaviate \
-e QUERY_DEFAULTS_LIMIT=25 \
-e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
-e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
-e DEFAULT_VECTORIZER_MODULE=text2vec-transformers \
-e ENABLE_MODULES=text2vec-transformers \
-e TEXT2VEC_TRANSFORMERS_INFERENCE_API=http://t2v-transformers:8080 \
semitechnologies/weaviate:latest注意：上面命令里的 t2v-transformers 是另一个容器的主机名。
如果只启动 Weaviate 本体，向量化模块会连不上。
更稳妥的做法是用 Docker Compose 同时启动 weaviate 和 t2v-transformers 两个服务，这里不展开完整 compose 文件，只提醒新手不要漏掉向量化容器。
启动后检查容器状态：
docker ps | grep weaviate
docker logs weaviate --tail 50日志里出现 server started 或监听 8080 的提示，说明服务已经起来了。
浏览器访问 http://服务器IP:8080/v1/meta，能返回 JSON 就代表接口正常。
建一个 collection 并导入第一条数据
Weaviate 用 collection 组织数据，类似关系库里的表。
下面用 REST 接口创建一个叫 Article 的 collection，并指定用 text2vec-transformers 自动向量化 title 和 content 字段：
curl -X POST http://localhost:8080/v1/schema \
-H "Content-Type: application/json" \
-d '{
"class": "Article",
"vectorizer": "text2vec-transformers",
"properties": [
{"name": "title", "dataType": ["text"]},
{"name": "content", "dataType": ["text"]}
]
}'创建成功后，导入一条数据：
curl -X POST http://localhost:8080/v1/objects \
-H "Content-Type: application/json" \
-d '{
"class": "Article",
"properties": {
"title": "服务器磁盘满了怎么清理",
"content": "先查大文件，再清日志和缓存，最后检查 inode 使用率。"
}
}'返回结果里会带一个 id，说明写入成功。
如果返回 422，通常是字段名和 schema 对不上，回到上一步检查 properties 定义。
执行一次相似度查询并验证结果
用 GraphQL 接口做语义检索，查和“磁盘空间不足”最接近的文章：
curl -X POST http://localhost:8080/v1/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "{ Get { Article(nearText: {concepts: [\"磁盘空间不足\"]}, limit: 3) { title content _additional { distance } } } }"
}'期望结果是刚才导入的那条数据排在前面，distance 越小表示越相似。
如果返回空数组，优先检查两件事：collection 名称大小写是否一致、向量化容器是否在运行（docker ps 看 t2v-transformers 状态）。
另一种验证方式是直接查对象数量：
curl http://localhost:8080/v1/objects?class=Article能列出刚写入的记录，说明数据持久化和查询链路都通了。
新手最容易踩的三个坑
- 只启动了 Weaviate，没启动向量化服务。 建 collection 不会报错，但导入数据时向量化会失败，日志里能看到连接
t2v-transformers超时。 - 把
localhost写进容器环境变量。 容器内的localhost指容器自己，不是宿主机。跨容器通信要用服务名或宿主机局域网 IP。 - 直接对外暴露 8080 且关闭鉴权。
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true只适合本地调试，公网环境要配置 API key 或 OIDC，否则任何人都能读写数据。
数据目录建议定期备份，单节点模式下删掉 /var/lib/weaviate 就等于清空全部向量和对象。
常见疑问
问：一定要用 text2vec-transformers 吗？ 不一定。
如果你自己生成向量，可以把 collection 的 vectorizer 设为 none，导入时在请求体里带上 vector 字段。
问：端口 8080 被占用了怎么办？ 把 -p 8080:8080 改成 -p 8081:8080，后续请求地址也跟着换成 8081，容器内端口不用动。
问：怎么确认数据真的持久化了？ 执行 docker restart weaviate 后再次查询 Article 集合，记录还在就说明挂载目录生效。
到这里，Weaviate 的最小可用链路已经跑通。
后续要接入真实业务，建议先用小批量数据验证向量化和检索效果，再考虑批量导入和性能调优。
