适用场景与部署思路

Weaviate 是一款广泛应用于 RAG 知识库、语义检索、向量搜索和多模态数据管理的向量数据库。与传统仅保存结构化字段的数据库不同，它能够将文本、图片描述、业务文档片段等内容转化为向量，并支持相似度检索、条件过滤、混合检索等强大功能。企业内网部署的核心目标，是在完全不依赖外部网络的前提下，让业务系统、AI 应用和内部知识库能够稳定、安全地调用向量检索服务。

内网部署通常分为三个层次：第一层是 Weaviate 服务本身，负责数据存储、索引构建和查询处理；第二层是向量化模型服务，可选择本地 embedding 模型，也可在内网提供统一的模型接口；第三层是业务接入层，例如知识库问答、工单检索、合同搜索、研发文档助手等。新手建议先用 Docker Compose 完成单机验证，再根据数据规模逐步升级到多节点或 Kubernetes 集群部署。

安装前准备

建议准备一台 Linux 服务器，推荐配置为 8 核 CPU、32GB 内存起步；如果仅用于测试，4 核 16GB 也可以运行。磁盘建议使用 SSD，容量根据数据量预估，向量索引会额外占用空间，通常需要预留原始文本数据的数倍容量。操作系统建议使用 Ubuntu Server、Debian、Rocky Linux 或其他企业常用发行版。

基础软件包括 Docker Engine、Docker Compose、curl、tar、vim 或其他文本编辑工具。内网环境需要提前准备镜像包，可在可联网环境下拉取对应镜像后导出，再导入内网服务器。常用镜像包括 semitechnologies/weaviate，以及本地向量模型服务所需镜像。版本选择上，生产环境不要盲目追新，建议选择近期稳定版本，并在测试环境完成兼容性验证。

离线镜像准备与导入

在可联网的准备机上执行镜像拉取，例如拉取 Weaviate 指定版本。完成后使用 docker save 导出为 tar 文件，再通过企业允许的文件传输方式放入内网服务器。内网服务器执行 docker load 导入镜像，并使用 docker images 确认镜像名称与标签是否正确。

如果需要本地 embedding 模型，也要同步准备模型文件和推理服务镜像。常见做法是将模型目录挂载到推理容器中，由 Weaviate 通过内网地址调用模型接口。对于新手来说，不建议一开始就把向量化、问答模型、业务服务全部塞进同一个容器，应保持各组件清晰分离，便于后续排错和扩容。

使用 Docker Compose 部署 Weaviate

创建部署目录，例如 /opt/weaviate，并在目录下编写 compose 配置。核心配置包括服务端口、数据目录、认证方式、持久化路径、默认向量化模块、集群节点名称等。单机入门可暴露 8080 作为 HTTP API 端口，50051 作为 gRPC 端口；生产环境应由内部网关或应用服务访问，不建议直接向大范围网段开放。

关键环境变量包括 QUERY_DEFAULTS_LIMIT，用于限制默认返回结果数量；AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED，生产环境建议关闭公开访问；PERSISTENCE_DATA_PATH，用于指定数据持久化目录；DEFAULT_VECTORIZER_MODULE，如果使用外部向量写入，可设置为 none；ENABLE_MODULES 用于启用 text2vec 等模块。完成配置后执行 docker compose up -d 启动，再用 docker ps 查看容器状态。

首次验证可以访问 /v1/meta 查看服务信息，访问 /v1/schema 查看当前集合定义。如果接口返回正常，说明服务已启动。接下来可创建一个简单集合，写入几条带向量或可被模型转向量的文本，再执行 nearVector 或 hybrid 查询验证检索效果。

接入本地向量模型

企业内网更推荐使用本地 embedding 服务，原因是可控、稳定且便于统一管理。接入方式有两种：一种是在业务侧先将文本转成向量，再把向量写入 Weaviate；另一种是启用 Weaviate 的向量化模块，由 Weaviate 调用模型服务完成向量化。新手排查问题时，第一种方式更直观，因为可以明确知道写入的向量维度和内容来源。

无论选择哪种方式，都要确保集合中定义的向量维度与模型输出一致。例如某模型输出 768 维，集合中写入的向量也必须是 768 维，否则会写入失败或查询异常。更换 embedding 模型时不能简单替换接口，旧数据向量与新模型向量空间不一致，通常需要重建向量并重新导入。

性能优化参数建议

Weaviate 的检索性能主要受内存、磁盘、向量维度、索引参数、数据量和查询并发影响。入门阶段最需要关注 HNSW 索引参数。efConstruction 影响建索引质量和写入开销，数值越高，构建越慢但召回效果可能更好；maxConnections 影响图连接数量，数值越高，索引占用空间越大。一般测试可使用默认值，生产环境可根据召回率和延迟逐步调优。

查询侧常见参数是 ef，它影响检索时搜索范围。ef 较高时召回更好，但延迟和 CPU 消耗也会上升。对于知识库问答场景，建议先以业务可接受的响应时间为上限，通过压测比较 ef=64、128、256 等配置的效果。对于高并发场景，应控制 topK 数量，不要默认返回过多结果，再由重排模型进行精排。

内存方面，向量索引会大量使用内存，服务器不应只按原始文档大小估算。建议为系统保留一定余量，避免容器无限制占用资源。可以在 Compose 中设置内存上限和重启策略，并对数据目录使用性能稳定的磁盘。批量导入时建议分批提交，例如每批 100 到 1000 条，根据文本长度、向量维度和机器配置调整，避免一次性写入过大导致超时。

如果数据包含大量业务字段，建议合理建立倒排索引，常用于部门、时间、文档类型、权限标签等过滤条件。不要给所有字段都建立复杂索引，字段越多，写入和存储压力越大。混合检索场景可以结合 BM25 与向量检索，但要通过实际样本调节权重，不能只看单次测试结果。

安全边界与权限建议

内网部署不等于天然安全。生产环境应关闭无认证访问，使用 API Key 或与内部身份系统对接，并通过网段、应用白名单、网关规则限制访问范围。数据目录要纳入备份策略，备份文件也应按敏感级别管理。日志中不要输出完整业务原文、密钥或用户隐私内容。

知识库类应用还要注意权限隔离。向量检索本身不会自动理解企业权限，如果不同用户只能访问不同文档，必须在写入数据时带上权限标签，并在查询时增加过滤条件。否则可能出现用户通过语义检索看到不该看到的内部资料。模型侧也要设置输入长度、请求频率和异常拦截，防止单个请求拖慢整体服务。

常见问题排查

问题一：容器启动后接口无法访问。先检查 docker ps 是否运行，再查看 docker logs 输出，确认端口是否被占用、数据目录权限是否正确、环境变量是否写错。若服务器启用了内部防护策略，还需确认应用服务器到 Weaviate 端口可达。

问题二：写入时报向量维度错误。通常是集合定义与 embedding 模型输出不一致，或新旧模型混用。解决方式是确认模型输出维度，重新创建集合或重建数据。生产环境不要直接在原集合上试错，应先在测试集合验证。

问题三：查询慢或结果不准。查询慢要检查 topK、ef、过滤条件和并发量；结果不准要检查分段策略、embedding 模型质量、是否混入无关文本、是否需要重排。很多知识库效果差并不是数据库问题，而是文档切分过长、标题丢失、表格结构破坏导致语义信息不足。

问题四：批量导入失败。可降低单批数量，增加客户端超时时间，观察内存与磁盘写入情况。导入大规模数据前建议先清洗重复文档、空内容和异常字符，并记录每条数据的来源 ID，便于失败重试和增量更新。

上线前检查清单

正式上线前，至少完成五项检查：第一，确认认证已开启，访问范围已限制；第二，确认数据目录持久化并有备份方案；第三，确认向量模型版本、维度、集合配置固定；第四，完成压测，记录平均延迟、峰值延迟、CPU、内存和磁盘指标；第五，准备回滚方案，包括镜像版本、配置文件、数据备份和启动命令。

对于企业新手团队，推荐先部署一套“小而稳”的 Weaviate 服务，接入一个低风险知识库场景，跑通导入、检索、权限过滤、监控和备份流程。等数据规模、访问模式和效果指标清晰后，再考虑多节点、高可用和更复杂的模型编排。这样既能降低安装门槛，也能避免一开始架构过重、排错困难。