# VecDB **Repository Path**: zzk123456/vec-db ## Basic Information - **Project Name**: VecDB - **Description**: 基于 HNSW (Hierarchical Navigable Small World) 算法的轻量级向量数据库，纯 Python 实现，支持持久化存储。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-01 - **Last Updated**: 2026-06-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VecDB VecDB 是一个轻量级 Python 向量数据库，适合本地 RAG 原型、个人知识库和小规模内部知识库服务。 它提供： - HNSW 风格的近似最近邻检索。 - Collection 创建、查询、删除、插入、搜索等基础 API。 - JSON + NumPy 本地持久化。 - Flask REST API 服务。 - 可选的本地 SentenceTransformer embedding 接口。 当前版本已经做过 P0 加固：collection 名称安全校验、核心状态加锁、持久化原子替换、API 参数校验、统一 JSON 错误响应，以及真实 embedding 模型接入。 ## 安装 基础安装： ```bash pip install -e . ``` 开发测试和本地 embedding 接口： ```bash pip install -e ".[dev,embedding]" ``` ## Python 直接使用 ```python import numpy as np from vecdb import VectorDB db = VectorDB(persist_dir="./vecdb_data") col = db.create_collection("docs", dim=4, metric="cosine") col.insert( np.array([1, 0, 0, 0], dtype=np.float32), metadata={"text": "hello"}, ) results = col.search(np.array([1, 0, 0, 0], dtype=np.float32), k=1) print(results) db.persist() ``` 搜索结果默认不返回完整向量，只返回 `id`、`distance` 和 `metadata`。如果确实需要返回向量： ```python col.search(query, k=5, include_vector=True) ``` ## 使用 text2vec 构建知识库 当前项目里模型建议放在： ```text models/text2vec-base-chinese ``` 可以运行示例： ```powershell python examples/text2vec_vecdb_demo.py ``` 这个示例会完成： ```text 中文文本 -> text2vec-base-chinese 生成 768 维向量 -> 写入 VecDB -> 用问题向量检索相似文本 ``` ## 启动 API 服务 PowerShell 示例： ```powershell python -m vecdb.server ` --host 127.0.0.1 ` --port 8900 ` --persist-dir ./vecdb_data ` --models-dir ./models ``` 管理端接口 `/api/v1/*` 面向本地控制台默认开放；OpenAI-compatible 入口 `/v1/*` 在创建 API-Key 后会校验 `Authorization: Bearer `。请仅在本机或可信内网中运行服务；如果要暴露到外部网络，建议先放到网关、反向代理或内网访问控制后面。 服务必须显式指定模型目录，前端模型下拉框只会读取 `--models-dir` 指向的目录。如果你的模型放在其他目录，替换参数值即可： ```powershell python -m vecdb.server ` --host 127.0.0.1 ` --port 8900 ` --persist-dir ./vecdb_data ` --models-dir ./models ``` 更新代码后需要重启服务，前端模型下拉框才会重新读取目录。 启动后打开浏览器访问： ```text http://127.0.0.1:8900/ ``` Web 控制台支持： - 查看和创建 Collection。 - 上传一个或多个 `.txt`、`.md`、`.markdown` 文档并自动切分入库。 - 在页面中直接提问测试知识库检索效果。 - 生成用于集成记录的 API-Key。 - 配置第三方 OpenAI-compatible AI 接口。 - 查看 `/v1/chat/completions` 调用示例。 ## REST API 示例 创建 collection： ```bash curl -X POST http://127.0.0.1:8900/api/v1/collections \ -H "Content-Type: application/json" \ -d '{"name": "docs", "embedding_model": "m3e-base", "metric": "cosine"}' ``` Web 控制台创建知识库时会从启动参数 `--models-dir` 指定的目录下动态读取可用向量模型，例如： ```text models/text2vec-base-chinese models/m3e-base ``` 创建 collection 时选择的 `embedding_model` 会绑定到该知识库，后续上传文档和问答检索都会使用这个模型；创建后不提供修改入口。如果需要换模型，建议新建 collection 并重新导入文档，避免不同模型生成的向量混用。 模型列表接口： ```http GET /api/v1/embedding-models ``` 插入向量： ```bash curl -X POST http://127.0.0.1:8900/api/v1/collections/docs/vectors \ -H "Content-Type: application/json" \ -d '{"vector": [0.1, 0.2, 0.3], "metadata": {"text": "hello"}}' ``` 搜索： ```bash curl -X POST http://127.0.0.1:8900/api/v1/collections/docs/search \ -H "Content-Type: application/json" \ -d '{"query": [0.1, 0.2, 0.3], "k": 5}' ``` 如果需要返回完整向量，在请求体里加入： ```json { "include_vector": true } ``` ## Embedding 接口 旧版演示用的伪 embedding 已移除。`/v1/embeddings` 和 `/v1/chat/completions` 需要真实的本地 SentenceTransformer 模型，例如： ```text models/text2vec-base-chinese ``` 生成 embedding，并可选写入 collection： ```bash curl -X POST http://127.0.0.1:8900/v1/embeddings \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"input": ["RAG 会检索知识库"], "collection": "docs"}' ``` 使用类 OpenAI Chat Completions 接口检索上下文： ```bash curl -X POST http://127.0.0.1:8900/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"model": "vecdb-rag:docs", "messages": [{"role": "user", "content": "什么是 RAG？"}], "k": 3}' ``` 注意：这个接口只返回检索到的上下文，不会调用大语言模型生成最终答案。你可以把返回的上下文交给自己的智能体或 LLM 使用。 如果在 Web 控制台或接口中启用了第三方 AI 配置，`/v1/chat/completions` 会先检索知识库上下文，再把上下文和用户问题转发给配置的第三方 AI，最终返回 AI 生成的回答。未配置或未启用第三方 AI 时，只返回检索上下文。 流式输出同样使用 OpenAI-compatible SSE 格式： ```bash curl -N -X POST http://127.0.0.1:8900/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"stream": true, "model": "vecdb-rag:docs", "messages": [{"role": "user", "content": "什么是 RAG？"}], "k": 3}' ``` 响应格式为 `Content-Type: text/event-stream`，每个事件以 `data: {...}` 输出，最后返回 `data: [DONE]`。如果启用了第三方 AI，平台会以 `stream=true` 请求第三方 AI 并透传其 SSE 输出；未启用第三方 AI 时，平台会把检索上下文按 Chat Completion Chunk 格式分片返回。 工具调用兼容： - 启用第三方 AI 时，`tools`、`tool_choice`、`functions`、`function_call`、`parallel_tool_calls`、`response_format` 等 Chat Completions 参数会透传给第三方 AI。 - 第三方 AI 返回的 `tool_calls`、`finish_reason: "tool_calls"` 等字段会原样返回给调用方。 - 当前平台自身不执行工具函数；工具执行仍由调用方智能体或第三方 AI 客户端流程负责。 ## 作为智能体的 AI 接口 可以把当前服务直接配置为其他智能体的 OpenAI-compatible AI 接口： ```text Base URL: http://127.0.0.1:8900/v1 API Key: Web 控制台或 /api/v1/api-keys 生成的 vdb_... 密钥 Model: vecdb-rag:docs ``` 其中 `docs` 是知识库 collection 名称。也可以请求时通过 `collection` 字段指定： ```json { "model": "vecdb-rag", "collection": "docs", "messages": [ {"role": "user", "content": "什么是 RAG？"} ], "k": 3 } ``` 模型列表接口： ```http GET /v1/models ``` 它会返回 `vecdb-rag` 和 `vecdb-rag:` 形式的模型 ID，便于智能体客户端选择知识库。 第三方 AI 接口需要兼容 OpenAI Chat Completions： ```text POST {base_url}/chat/completions ``` 请求体会包含： ```json { "model": "你配置的模型名", "messages": [ {"role": "system", "content": "包含检索上下文的系统提示词"}, {"role": "user", "content": "用户问题"} ] } ``` ## 上传文档接口 Web 控制台上传文档使用的是： ```http POST /api/v1/documents/upload ``` 表单字段： | 字段 | 说明 | | --- | --- | | `file` | 文档文件，当前支持 `.txt`、`.md`、`.markdown` | | `files` | 多文档上传字段，可重复传多个文件 | | `collection` | 写入的 collection 名称，默认 `docs` | | `embedding_model` | collection 不存在时用于自动创建并绑定的向量模型 | | `chunk_size` | 文本切片长度，默认 `500` | | `overlap` | 相邻切片重叠长度，默认 `80` | 上传后会自动完成： ```text 文档文本 -> 文本切片 -> embedding -> 写入 VecDB -> 持久化 ``` ## API-Key 管理 Web 控制台可以生成 API-Key，接口为： ```http POST /api/v1/api-keys GET /api/v1/api-keys DELETE /api/v1/api-keys/ ``` 生成后的 API-Key 用于调用 OpenAI-compatible 入口 `/v1/*`，其他智能体应配置： ```text Base URL: http://127.0.0.1:8900/v1 API Key: vdb_... ``` 请求时服务端会校验 `Authorization: Bearer vdb_...`。管理端接口 `/api/v1/*` 仍保持本地控制台可直接访问；全新环境尚未创建任何 API-Key 时，`/v1/*` 会允许访问，方便首次初始化和本地测试。 ## 主要接口 | 方法 | 路径 | 说明 | | --- | --- | --- | | `GET` | `/api/v1/health` | 健康检查 | | `GET` | `/api/v1/embedding-models` | 列出 `models/` 目录下可选向量模型 | | `GET` | `/api/v1/collections` | 列出 collection | | `POST` | `/api/v1/collections` | 创建 collection | | `GET` | `/api/v1/collections/` | 查看 collection 信息 | | `DELETE` | `/api/v1/collections/` | 删除 collection | | `POST` | `/api/v1/collections//vectors` | 插入单条或批量向量 | | `POST` | `/api/v1/collections//search` | 搜索相似向量 | | `GET` | `/api/v1/collections//vectors/` | 获取单条向量 | | `DELETE` | `/api/v1/collections//vectors/` | 删除单条向量 | | `POST` | `/api/v1/persist` | 持久化所有 collection | | `POST` | `/api/v1/documents/upload` | 上传文档并写入知识库 | | `GET` | `/api/v1/settings/ai` | 查看第三方 AI 配置 | | `POST` | `/api/v1/settings/ai` | 保存第三方 AI 配置 | | `POST` | `/api/v1/settings/ai/test` | 测试第三方 AI 连接 | | `GET` | `/api/v1/api-keys` | 查看 API-Key 列表 | | `POST` | `/api/v1/api-keys` | 创建 API-Key | | `DELETE` | `/api/v1/api-keys/` | 删除 API-Key | | `POST` | `/v1/embeddings` | 生成 embedding，可选写入 VecDB | | `POST` | `/v1/chat/completions` | 检索知识库上下文 | | `GET` | `/v1/models` | OpenAI-compatible 模型列表 | ## 安全和投产说明 - Collection 名称只能包含字母、数字、下划线和连字符。 - 持久化会先写新的向量快照，再原子替换 `meta.json`。 - API 错误统一返回 `{"error": "..."}`。 - Collection、索引和持久化相关操作已加锁，适合低并发内部服务。 - 搜索默认不返回向量，避免响应体过大。 - OpenAI-compatible 入口 `/v1/*` 会在已有 API-Key 时校验 Bearer Token；管理端 `/api/v1/*` 仍建议放在内网、网关或反向代理后面。 当前项目适合本地原型、小规模内部知识库和智能体 RAG 工具试运行。如果要承载高并发、多租户或强 SLA 生产服务，建议继续做 P1/P2 优化，例如日志监控、备份恢复、metadata filter、召回率/延迟 benchmark，以及考虑使用 FAISS、hnswlib、Qdrant 或 Milvus 等成熟向量引擎。 ## 测试 ```bash python -m pytest -q ```