Weaviate REST API：HTTP接口详细文档-优快云博客

Weaviate REST API：HTTP接口详细文档

【免费下载链接】weaviate Weaviate is an open source vector database that stores both objects and vectors, allowing for combining vector search with structured filtering with the fault-tolerance and scalability of a cloud-native database, all accessible through GraphQL, REST, and various language clients. 项目地址: https://gitcode.com/GitHub_Trending/we/weaviate

概述

Weaviate是一个开源的向量数据库（Vector Database），它通过RESTful API提供完整的CRUD操作、向量搜索和语义查询功能。本文档详细介绍了Weaviate的REST API接口，帮助开发者快速上手和使用。

基础配置

API端点基础URL

http://localhost:8080/v1

请求头配置

Content-Type: application/json
Authorization: Bearer {api-key}  # 如果启用认证

核心API接口

1. 模式管理（Schema）

获取所有类（Class）

GET /v1/schema

响应示例：

{
  "classes": [
    {
      "class": "Article",
      "properties": [
        {
          "name": "title",
          "dataType": ["text"]
        },
        {
          "name": "content",
          "dataType": ["text"]
        }
      ]
    }
  ]
}

创建新类

POST /v1/schema
Content-Type: application/json

{
  "class": "Product",
  "properties": [
    {
      "name": "name",
      "dataType": ["text"]
    },
    {
      "name": "price",
      "dataType": ["number"]
    }
  ]
}

2. 数据操作（Objects）

创建对象

POST /v1/objects
Content-Type: application/json

{
  "class": "Article",
  "properties": {
    "title": "Weaviate入门指南",
    "content": "Weaviate是一个强大的向量数据库..."
  },
  "vector": [0.1, 0.2, 0.3, ...]  # 可选，自动生成
}

批量创建对象

POST /v1/batch/objects
Content-Type: application/json

{
  "objects": [
    {
      "class": "Article",
      "properties": {
        "title": "文章1",
        "content": "内容1"
      }
    },
    {
      "class": "Article",
      "properties": {
        "title": "文章2",
        "content": "内容2"
      }
    }
  ]
}

获取对象

GET /v1/objects/{id}

更新对象

PUT /v1/objects/{id}
Content-Type: application/json

{
  "properties": {
    "title": "更新后的标题"
  }
}

删除对象

DELETE /v1/objects/{id}

3. 向量搜索（Vector Search）

基础向量搜索

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        nearVector: {
          vector: [0.1, 0.2, 0.3, ...]
        }
        limit: 10
      ) {
        title
        content
        _additional {
          distance
        }
      }
    }
  }"
}

文本语义搜索

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        nearText: {
          concepts: [\"机器学习\", \"人工智能\"]
        }
        limit: 5
      ) {
        title
        content
        _additional {
          distance
        }
      }
    }
  }"
}

混合搜索（向量+过滤）

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        nearText: {
          concepts: [\"深度学习\"]
        }
        where: {
          operator: Equal,
          path: [\"category\"],
          valueString: \"技术\"
        }
        limit: 10
      ) {
        title
        content
        category
      }
    }
  }"
}

4. 聚合查询（Aggregations）

统计聚合

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Aggregate {
      Article {
        meta {
          count
        }
        groupedBy {
          path: [\"category\"]
          value
        }
      }
    }
  }"
}

5. 批处理操作

批量导入数据

POST /v1/batch/objects
Content-Type: application/json

{
  "objects": [
    {
      "class": "Article",
      "properties": {
        "title": "批量文章1",
        "content": "内容1",
        "category": "技术"
      }
    },
    {
      "class": "Article", 
      "properties": {
        "title": "批量文章2",
        "content": "内容2",
        "category": "新闻"
      }
    }
  ]
}

高级搜索功能

多向量搜索

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        nearVector: {
          vector: [0.1, 0.2, 0.3, ...]
          certainty: 0.8
        }
        nearText: {
          concepts: [\"人工智能\"]
          certainty: 0.7
        }
        limit: 5
      ) {
        title
        content
        _additional {
          certainty
        }
      }
    }
  }"
}

过滤条件组合

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        where: {
          operator: And,
          operands: [
            {
              operator: Equal,
              path: [\"category\"],
              valueString: \"技术\"
            },
            {
              operator: GreaterThan,
              path: [\"views\"],
              valueInt: 1000
            }
          ]
        }
        limit: 10
      ) {
        title
        views
        category
      }
    }
  }"
}

错误处理

常见HTTP状态码

状态码	含义	描述
200	OK	请求成功
201	Created	对象创建成功
400	Bad Request	请求参数错误
401	Unauthorized	认证失败
404	Not Found	资源不存在
500	Internal Error	服务器内部错误

错误响应格式

{
  "error": [
    {
      "message": "Invalid query syntax",
      "path": ["query"]
    }
  ]
}

性能优化建议

批量操作最佳实践

// 推荐：批量处理100个对象一组
const batchSize = 100;
for (let i = 0; i < objects.length; i += batchSize) {
  const batch = objects.slice(i, i + batchSize);
  await weaviate.batch.create(batch);
}

查询优化技巧

POST /v1/graphql
Content-Type: application/json

{
  "query": "{
    Get {
      Article(
        nearVector: {
          vector: [0.1, 0.2, 0.3, ...]
          distance: 0.2  # 设置距离阈值提高性能
        }
        limit: 10
        # 只返回需要的字段
      ) {
        title
        content
        _additional {
          distance
        }
      }
    }
  }"
}

安全配置

API密钥认证

POST /v1/objects
Content-Type: application/json
Authorization: Bearer your-api-key-here

{
  "class": "Article",
  "properties": {
    "title": "安全文章",
    "content": "需要认证的内容"
  }
}

CORS配置

services:
  weaviate:
    environment:
      - ORIGINS=http://localhost:3000,https://yourdomain.com

监控和日志

健康检查

GET /v1/.well-known/ready

版本信息

GET /v1/meta

性能指标

GET /v1/metrics

总结

Weaviate的REST API提供了完整的向量数据库功能，包括：

✅ 完整的CRUD操作
✅ 强大的向量搜索能力
✅ 灵活的过滤和聚合
✅ 批量操作支持
✅ 完善的错误处理
✅ 安全认证机制

通过合理使用这些API接口，开发者可以构建高效的语义搜索应用、推荐系统和知识管理平台。

下一步学习建议：

探索GraphQL API的高级查询功能
学习如何集成不同的向量化模型
了解Weaviate的集群部署和扩展方案
实践构建真实的AI搜索应用场景

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考