Skip to content

vector-store.md

Latest commit

 

History

History
361 lines (289 loc) · 9.92 KB

vector-store.md

File metadata and controls

361 lines (289 loc) · 9.92 KB

Vector Store API

返回目录

向量存储（VectorStore）API 用于管理向量数据库连接配置。支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、SQLite 六种引擎类型。

方法 路径 描述
GET /vector-stores/types 获取支持的引擎类型及配置字段
POST /vector-stores/test 使用原始凭据测试连接（不保存）
POST /vector-stores 创建向量存储
GET /vector-stores 获取向量存储列表
GET /vector-stores/:id 获取向量存储详情
PUT /vector-stores/:id 更新向量存储（仅名称可修改）
DELETE /vector-stores/:id 删除向量存储（软删除）
POST /vector-stores/:id/test 测试已保存的向量存储连接

GET /vector-stores/types - 获取支持的引擎类型

返回所有支持的引擎类型，包含连接配置和索引配置的字段定义，可用于前端表单生成。

请求:

curl --location 'http://localhost:8080/api/v1/vector-stores/types' \
--header 'X-API-Key: sk-xxxxx'

响应:

{
    "success": true,
    "data": [
        {
            "type": "elasticsearch",
            "display_name": "Elasticsearch (Keywords + Vector)",
            "connection_fields": [
                {"name": "addr", "type": "string", "required": true, "description": "Elasticsearch URL (e.g., http://localhost:9200)"},
                {"name": "username", "type": "string", "required": false},
                {"name": "password", "type": "string", "required": false, "sensitive": true}
            ],
            "index_fields": [
                {"name": "index_name", "type": "string", "required": false, "default": "xwrag_default"},
                {"name": "number_of_shards", "type": "number", "required": false},
                {"name": "number_of_replicas", "type": "number", "required": false}
            ]
        },
        {
            "type": "postgres",
            "display_name": "PostgreSQL (Keywords + Vector)",
            "connection_fields": [
                {"name": "use_default_connection", "type": "boolean", "required": false, "default": true, "description": "Use the application's default database connection"},
                {"name": "addr", "type": "string", "required": false, "description": "PostgreSQL connection string (required if use_default_connection is false)"},
                {"name": "username", "type": "string", "required": false},
                {"name": "password", "type": "string", "required": false, "sensitive": true}
            ]
        }
    ]
}

POST /vector-stores/test - 测试原始凭据连接

使用提供的凭据执行连接测试，不保存任何数据。成功时返回自动检测到的服务器版本。

请求:

curl --location 'http://localhost:8080/api/v1/vector-stores/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "engine_type": "elasticsearch",
    "connection_config": {
        "addr": "http://es:9200",
        "username": "elastic",
        "password": "changeme"
    }
}'

响应（成功）:

{
    "success": true,
    "version": "7.10.1"
}

version 字段包含自动检测到的服务器版本。如果无法检测（如 Milvus、SQLite），则为空字符串。

响应（失败）:

{
    "success": false,
    "error": "failed to connect to elasticsearch: connection refused or authentication failed"
}

POST /vector-stores - 创建向量存储

创建一个新的向量存储配置。同一 endpoint + index 组合不允许重复注册（包括环境变量配置的存储）。

请求:

curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "name": "elasticsearch-hot",
    "engine_type": "elasticsearch",
    "connection_config": {
        "addr": "http://es-hot:9200",
        "username": "elastic",
        "password": "changeme"
    },
    "index_config": {
        "index_name": "my_index"
    }
}'

响应 (201):

{
    "success": true,
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "elasticsearch-hot",
        "engine_type": "elasticsearch",
        "connection_config": {
            "addr": "http://es-hot:9200",
            "username": "elastic",
            "password": "***"
        },
        "index_config": {
            "index_name": "my_index"
        },
        "source": "user",
        "readonly": false,
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
    }
}

注意: 响应中的敏感字段（password、api_key）会被掩码为 "***"。 connection_config.version 字段在连接测试成功后自动填充（如 "7.10.1"），创建时为空。

GET /vector-stores - 获取向量存储列表

返回当前租户的所有向量存储，包含环境变量配置的存储（source: "env"）和用户创建的存储（source: "user"）。环境变量存储排列在前。

请求:

curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx'

响应:

{
    "success": true,
    "data": [
        {
            "id": "__env_postgres__",
            "name": "postgres (env)",
            "engine_type": "postgres",
            "connection_config": {
                "use_default_connection": true
            },
            "source": "env",
            "readonly": true
        },
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "elasticsearch-hot",
            "engine_type": "elasticsearch",
            "connection_config": {
                "addr": "http://es-hot:9200",
                "username": "elastic",
                "password": "***"
            },
            "source": "user",
            "readonly": false
        }
    ]
}

GET /vector-stores/:id - 获取向量存储详情

根据 ID 获取单个向量存储详情。支持 __env_* 格式的环境变量存储 ID。

请求:

curl --location 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'

响应:

{
    "success": true,
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "elasticsearch-hot",
        "engine_type": "elasticsearch",
        "connection_config": {
            "addr": "http://es-hot:9200",
            "username": "elastic",
            "password": "***",
            "version": "7.10.1"
        },
        "index_config": {
            "index_name": "my_index"
        },
        "source": "user",
        "readonly": false,
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:00:00Z"
    }
}

PUT /vector-stores/:id - 更新向量存储

更新向量存储的名称。engine_type、connection_config、index_config 创建后不可变更。环境变量存储不可修改（返回 400）。

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "name": "elasticsearch-hot-renamed"
}'

响应:

{
    "success": true,
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "elasticsearch-hot-renamed",
        "engine_type": "elasticsearch",
        "connection_config": {
            "addr": "http://es-hot:9200",
            "username": "elastic",
            "password": "***"
        },
        "index_config": {
            "index_name": "my_index"
        },
        "source": "user",
        "readonly": false,
        "created_at": "2026-04-07T10:00:00Z",
        "updated_at": "2026-04-07T10:05:00Z"
    }
}

DELETE /vector-stores/:id - 删除向量存储

软删除向量存储。环境变量存储不可删除（返回 400）。

请求:

curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'

响应:

{
    "success": true
}

POST /vector-stores/:id/test - 测试已保存的向量存储连接

对已保存的向量存储或环境变量存储执行连接测试。成功时返回检测到的服务器版本，并自动更新存储记录中的 connection_config.version 字段。

请求:

curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000/test' \
--header 'X-API-Key: sk-xxxxx'

响应（成功）:

{
    "success": true,
    "version": "7.10.1"
}

对于已保存的存储（非环境变量存储），检测到的版本会自动保存到 connection_config.version 中。

响应（失败）:

{
    "success": false,
    "error": "failed to connect to elasticsearch: connection refused or authentication failed"
}

环境变量存储

通过 RETRIEVE_DRIVER 环境变量配置的向量存储以虚拟条目形式出现在列表中。这些条目的特征：

  • ID 格式: __env_{driver}__（如 __env_postgres__、__env_elasticsearch_v8__）
  • source: "env"
  • readonly: true
  • 不可修改/删除: PUT 和 DELETE 返回 400
  • 可测试连接: POST /:id/test 正常工作

错误码

HTTP 状态码 含义
400 请求参数错误、验证失败、尝试修改环境变量存储
401 未认证
404 向量存储不存在
409 同一 endpoint + index 组合已存在
500 内部服务器错误