Weaviate Cookbooks 应用构建指南
为使用 Weaviate 构建全栈 AI 应用提供架构模式、端到端蓝图与最佳实践的索引型技能。
凭据通过环境变量而非硬编码传递，模板要求 .env 本地化并 gitignore；规则明确“仅在请求时修改用户集合”“仅填写实际使用的密钥”，最小权限与确认机制可见。扣分：未展示回滚机制，re-ranker 会话内修改集合配置仅有口头限制，引用的 project_setup.md 契约未见内容，缺乏对发送到 Weaviate Cloud 的数据流向的系统说明。
各 cookbook 内部自洽，安装集、环境变量、代码片段相互一致，async_client.md 的同步/异步区分与常见陷阱记录详实。扣分：无任何提交的测试或 CI 证据覆盖关键路径，故障处理多依赖“广泛使用 web 搜索”，故障反馈质量不足，静态评审下不能超过 10。
描述与索引清晰列出八类场景，触发条件（用户想用 Weaviate 构建 AI 应用）语义明确，non-fit（非 Weaviate agent 可省略 WEAVIATE_*）有说明。扣分：核心功能完全依赖 Weaviate Cloud 及海外 LLM 提供商，从中国大陆可达性存疑且未披露边界与备选方案，中文环境支持未提及。
信息架构分层良好（索引→共享规范→各 cookbook），环境要求集中且提供规范 .env 模板，README 含安装与安全说明，仓库带 BSD-3-Clause 许可证。扣分：无版本号、变更日志或明确维护责任说明，部分引用文件（project_setup.md）内容未在证据中呈现，Node 版本要求 v25.3.0+ 显得非常规且未解释。
skill 提供可复用的架构模式与最佳实践蓝图，索引结构使代理可直接生成完整应用，边际价值明确。扣分：静态评审无法验证生成结果可直接使用，代码多处为片段（'...existing code'、'import client here'），完成度依赖代理自行补全，无代表性输出验证证据。
大量链接指向官方文档、论坛与 GitHub issue，可交叉核对；事实与建议基本分开。扣分：静态评审无执行复现，无提交的测试套件或 CI 覆盖证据，代码示例的运行正确性无法独立证实，静态上限 5 之下取 4。
- 核心功能依赖 Weaviate Cloud 与海外 LLM 提供商，中国大陆网络可达性未披露，使用前请确认网络环境。
- 本评审为纯静态源码评审，未执行任何代码；关键路径无可复现测试证据。
- 部分代码为片段（'...existing code' 等），生成应用的完整性取决于代理补全质量。
- 无版本号与变更日志，内容可能随上游 Weaviate API 演进而失效。
- 引用的 project_setup.md 内容未在本次证据中呈现，使用前建议自行审阅该契约文件。
这个 Skill 能做什么，适合哪些场景？
weaviate-cookbooks 是 Weaviate 官方 agent-skills 仓库中的一个技能，定位为 Weaviate 应用实现指南的索引。它覆盖七个具体蓝图：Query Agent 聊天机器人、数据浏览器、多模态 PDF RAG、基础 RAG、高级 RAG、基础 Agent（DSPy）和 Agentic RAG，并附带可选的 Next.js 前端与异步客户端指南。技能强调共享的项目搭建契约与环境要求，并指导用户通过 Weaviate Cloud 免费沙箱创建实例。适合已有或计划使用 Weaviate 的开发者快速搭建遵循官方最佳实践的全栈应用。
该技能本身是一组 Markdown 参考文档，供编码代理按需读取：先加载项目搭建契约与环境要求两个共享参考，再按用户需求选择对应的 cookbook 参考（如 Query Agent Chatbot 或 Agentic RAG）生成完整的应用代码；可选加载 Next.js 前端指南和 Weaviate Python 异步客户端的生产使用指南（连接管理、生命周期、多集群配置）。它还引导没有实例的用户到 Weaviate Cloud 控制台注册免费沙箱。
- 后端开发者想用 Weaviate Query Agent 快速搭一个支持流式输出和聊天历史的全栈聊天机器人
- 数据团队需要给 Weaviate 中的数据做一个带排序、关键词搜索和表格视图的浏览器界面
- 构建多模态文档搜索：用 Weaviate Embeddings（ModernVBERT/colmodernvbert）加 Ollama Qwen3-VL 处理 PDF
- 工程师想从基础 RAG 升级到带重排序、查询分解、查询改写的进阶版本
- 使用 DSPy 构建带结构化输出的工具调用 Agent 或带层级 RAG 工具的 Agentic RAG 应用
- 需要为已有的 Weaviate 后端补一个 Next.js 前端
这个 Skill 有哪些优点和局限？
- Weaviate 官方维护，BSD-3-Clause 许可，内容与产品演进同步
- 覆盖从基础 RAG 到 Agentic RAG、多模态、Agent 的完整进阶路径
- 每个蓝图附最佳实践：连接管理、环境要求、项目结构契约
- 附带异步客户端生产指南和可选前端方案，实用性强
- 强绑定 Weaviate 生态，不适用于其他向量数据库
- 缺少测试套件或质量验证的证据，蓝图质量需自行评估
- 多模态 RAG 依赖 Ollama + Qwen3-VL 等外部组件，本地资源要求未量化
- 源文档未说明单个技能能否脱离集合独立安装
如何安装这个 Skill？
通过任意兼容 Agent Skills 格式的客户端安装整个技能集合：运行 npx skills add weaviate/agent-skills（适用于 Cursor、Claude Code、Gemini CLI 等），或在 Claude Code 中执行 /plugin marketplace add weaviate/agent-skills 再 /plugin install weaviate@weaviate-plugins，或手动 git clone https://github.com/weaviate/agent-skills.git 后将代理指向该目录。该技能位于仓库内的 skills/weaviate-cookbooks/。安装前需配置 WEAVIATE_URL 和 WEAVIATE_API_KEY 环境变量；如何单独安装集合中的某一个技能，源文档未说明。
如何使用这个 Skill？
在兼容代理中直接描述需求即可触发，例如："Build a chatbot using the Query Agent"、"Build a multimodal RAG app for my PDF documents" 或 "Build an agentic RAG app"。代理会读取技能内的索引与对应参考文档，按项目搭建契约生成代码。若无 Weaviate 实例，先到 console.weaviate.cloud 注册免费沙箱。
这个 Skill 与同类方案有什么区别？
同仓库中的 weaviate 技能提供直接操作 Weaviate 数据库的工具函数（建集合、查询、导入数据）；本技能则聚焦于生成完整应用代码的蓝图，两者互补而非替代。