weaviate

Weaviate 数据库操作

此技能提供对 Weaviate 向量数据库的全面访问，包括搜索操作、自然语言查询、架构检查、数据探索、筛选获取、集合创建和数据导入。

Weaviate Cloud 实例

如果用户还没有实例，请引导他们前往云控制台注册并创建免费沙盒。通过 Weaviate Cloud 创建 Weaviate 实例。

环境变量

必需：

• WEAVIATE_URL - Weaviate Cloud 集群 URL
• WEAVIATE_API_KEY - Weaviate API 密钥

外部提供商密钥（自动检测）： 仅设置集合使用的密钥。更多信息请参阅环境要求。

运行脚本

命令从 SKILL_DIR 开始执行，它是包含此 SKILL.md 的文件夹的绝对路径。运行前请替换该路径，并从用户的项目中运行命令，以便像 data.csv 这样的文件参数能相对于项目进行解析：

uv run /path/to/skills/weaviate/scripts/list_collections.py

脚本索引

搜索与查询

• 查询 Agent - Ask 模式：当用户希望基于集合数据获得直接答案时使用。查询 Agent 会综合一个或多个集合中的信息，并返回包含来源引用（集合名称和对象 ID）的结构化响应。
• 查询 Agent - 搜索模式：当用户希望跨一个或多个集合探索或浏览原始对象时使用。与 Ask 模式不同，此模式返回实际数据对象，而非综合后的答案。
• 混合搜索：**大多数搜索的默认选择。**在语义理解和精确关键词匹配之间取得良好平衡。不确定该选择哪种搜索类型时使用此方式。
• 语义搜索：用于查找概念相似的内容，不受具体措辞影响。当意图比特定关键词更重要时最适用。
• 关键词搜索：用于查找确切术语、ID、SKU 或特定文本模式。需要精确匹配关键词而非语义相似性时最适用。

集合管理

• 列出集合：用于发现 Weaviate 实例中有哪些集合。通常应在执行任何搜索或数据操作前首先使用。
• 获取集合详情：用于了解集合的架构——其属性、数据类型、向量化器配置、副本因子和多租户状态。在运行搜索或导入前很有帮助。
• 探索集合：用于分析数据分布、热门值并检查集合中的实际内容。在查询前了解数据情况时很有帮助。
• 创建集合：用于在导入数据前使用自定义架构创建新集合。除非用户明确要求，否则不要指定向量化器（默认使用 text2vec_weaviate）。

数据操作

• 获取与筛选：用于按 ID 检索特定对象或检索经过严格筛选的数据子集。适用于精确检索数据，而非搜索。
• 导入数据：**当用户要求将文件（CSV、JSON、JSONL、PDF）导入、加载或摄取到集合中时使用。**在免费套餐集群上，如果导入 PDF 时必须创建集合，则会被拒绝；请参阅免费套餐集群。
• 创建示例数据：当没有可用数据或用户要求一些玩具数据时，用于创建可供其他技能立即使用的示例数据。

免费套餐集群

Weaviate Cloud 免费套餐集群有一些限制，且这些限制可能会变化；如果脚本报错与本节内容矛盾，请以报错为准。

• 只能有一个集合。 创建第二个集合会被拒绝，并返回 429 USAGE_LIMIT_EXCEEDED（“collections count limit of 1 reached”）。请先运行 list_collections.py。如果已有集合，请导入该集合，而不要再创建一个，并在使用唯一名额前征求用户同意。
• example_data.py 会占用该名额。 example_data.py 会创建一个集合，名称取决于 --domain（默认值 academic 对应 AI_Arxiv；其他值对应 Income_Tax_Returns、Product_Catalog、Hair_Medical 或 IT_Support_Tickets）。除非用户同意占用该名额，否则不要运行此脚本。对 PDF 运行 import.py 时，如果集合不存在，脚本会自动创建集合；在免费套餐集群上，如果 PDF 导入需要创建集合，则会被拒绝，并返回 422 CONFIG_NOT_ALLOWED；如果用户提出此类请求，请让用户决定。这里没有任何脚本会删除集合。
• 只接受 hfresh 向量索引。 如果创建时请求其他类型（例如 hnsw），会被拒绝，并返回 422 CONFIG_NOT_ALLOWED。脚本固定使用 weaviate-client 4.23.1，该版本会将索引类型交由服务端决定；较旧的客户端会请求 hnsw，因此会被拒绝。如果 422 错误指出 4.23.1 或更高版本不允许使用 hnsw，请告知用户，不要重试。

建议

1. 首先列出集合，了解有哪些可用集合：

   uv run SKILL_DIR/scripts/list_collections.py
   

2. 如果没有可用集合，且用户提出请求，询问用户是否要创建示例数据。否则继续操作。

   uv run SKILL_DIR/scripts/example_data.py
   

3. 获取集合详情，以了解其架构：

   uv run SKILL_DIR/scripts/get_collection.py --name "COLLECTION_NAME"
   

4. 浏览集合数据，查看值和统计信息：

   uv run SKILL_DIR/scripts/explore_collection.py "COLLECTION_NAME"
   

5. 如果要导入新的 CSV、JSON 或 JSONL 文件，创建集合——导入前必须先创建集合：

   uv run SKILL_DIR/scripts/create_collection.py CollectionName \
     --properties '[{"name": "title", "data_type": "text"}, {"name": "body", "data_type": "text"}]'
   

   除非用户明确要求，否则不要指定向量化器。

6. 将数据导入现有集合：

   uv run SKILL_DIR/scripts/import.py "data.csv" --collection "CollectionName"
   

   对于 PDF 导入，系统会自动创建集合——跳过第 5 步。在免费套餐集群上，如果 PDF 导入需要创建集合，则会被拒绝；请参阅免费套餐集群。

7. 选择合适的搜索类型：

   • 在多个集合中获取带来源引用的 AI 生成答案 → ask.py
   • 从多个集合中获取原始对象 → query_search.py
   • 一般搜索 → hybrid_search.py（默认）
   • 概念相似性搜索 → semantic_search.py
   • 精确匹配词语或 ID → keyword_search.py

输出格式

所有脚本都支持：

• Markdown 表格（默认且推荐）
• JSON（--json 标志）

错误处理

常见错误：

• WEAVIATE_URL not set → 设置环境变量
• Collection not found → 使用 list_collections.py 查看可用集合
• Authentication error → 检查 Weaviate 和向量化器提供商的 API 密钥