houyidb 0.2.0b5__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- houyidb-0.2.0b5/PKG-INFO +56 -0
- houyidb-0.2.0b5/README.md +42 -0
- houyidb-0.2.0b5/houyidb/__init__.py +36 -0
- houyidb-0.2.0b5/houyidb/client.py +339 -0
- houyidb-0.2.0b5/houyidb.egg-info/PKG-INFO +56 -0
- houyidb-0.2.0b5/houyidb.egg-info/SOURCES.txt +9 -0
- houyidb-0.2.0b5/houyidb.egg-info/dependency_links.txt +1 -0
- houyidb-0.2.0b5/houyidb.egg-info/requires.txt +1 -0
- houyidb-0.2.0b5/houyidb.egg-info/top_level.txt +1 -0
- houyidb-0.2.0b5/pyproject.toml +22 -0
- houyidb-0.2.0b5/setup.cfg +4 -0
houyidb-0.2.0b5/PKG-INFO
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: houyidb
|
|
3
|
+
Version: 0.2.0b5
|
|
4
|
+
Summary: Python SDK for HouyiDB — single-node vector database (collections HTTP API)
|
|
5
|
+
Author: HouyiDB Contributors
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://houyidb.top
|
|
8
|
+
Project-URL: Repository, https://github.com/houyidb-community/houyidb
|
|
9
|
+
Project-URL: Documentation, https://github.com/houyidb-community/houyidb/blob/main/docs/USER_MANUAL.md
|
|
10
|
+
Keywords: vector-database,hnsw,rag,houyidb
|
|
11
|
+
Requires-Python: >=3.9
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
Requires-Dist: requests>=2.28
|
|
14
|
+
|
|
15
|
+
# houyidb — HouyiDB Python SDK
|
|
16
|
+
|
|
17
|
+
> [English](README.en.md)
|
|
18
|
+
|
|
19
|
+
HouyiDB collections HTTP API 的薄封装:传输 + 类型,不含框架语义。
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
from houyidb import HouyiClient, Vector, Filter
|
|
23
|
+
|
|
24
|
+
client = HouyiClient("http://127.0.0.1:7000")
|
|
25
|
+
col = client.collection("goods") # 首次 upsert 时隐式创建
|
|
26
|
+
|
|
27
|
+
col.upsert([
|
|
28
|
+
Vector(id=1, values=[0.9, 0.1], payload={"name": "apple", "price": 3.5}),
|
|
29
|
+
Vector(id=2, values=[0.1, 0.9], payload={"name": "laptop", "price": 8999}),
|
|
30
|
+
])
|
|
31
|
+
|
|
32
|
+
res = col.hybrid_search(
|
|
33
|
+
[0.85, 0.15], k=3,
|
|
34
|
+
filters=[Filter("price", "lt", 1000)],
|
|
35
|
+
include_payload=True,
|
|
36
|
+
)
|
|
37
|
+
for hit in res.hits:
|
|
38
|
+
print(hit.id, hit.score, hit.payload)
|
|
39
|
+
|
|
40
|
+
col.delete([1]) # 按 id
|
|
41
|
+
col.delete(filters=[Filter("price", "lt", 100)]) # 按条件(标量页求值,刚写入即可命中)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## 契约要点
|
|
45
|
+
|
|
46
|
+
- **相似度分数**:`1 - cosine_distance`,越大越相似(余弦后端)。
|
|
47
|
+
- **过滤算子**:`eq` / `gt` / `lt` / `gte` / `lte` / `in`,多条取交集。
|
|
48
|
+
- **保留键**:payload 不得使用 `label` 键(400),label 走顶层字段。
|
|
49
|
+
- **id 空间**:u64;`houyidb.stable_id(str)` 可把字符串 id 确定性映射进 u64。
|
|
50
|
+
- **v1 易失性**:collection 的 payload/标量页不写 WAL,进程重启后丢失(向量索引不受影响)。
|
|
51
|
+
- **错误**:非 2xx 一律抛 `HouyiError(status_code, message)`。
|
|
52
|
+
|
|
53
|
+
## 生态 adapter
|
|
54
|
+
|
|
55
|
+
- `langchain-houyidb` — LangChain `VectorStore` 实现
|
|
56
|
+
- `llama-index-vector-stores-houyidb` — LlamaIndex `BasePydanticVectorStore` 实现
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# houyidb — HouyiDB Python SDK
|
|
2
|
+
|
|
3
|
+
> [English](README.en.md)
|
|
4
|
+
|
|
5
|
+
HouyiDB collections HTTP API 的薄封装:传输 + 类型,不含框架语义。
|
|
6
|
+
|
|
7
|
+
```python
|
|
8
|
+
from houyidb import HouyiClient, Vector, Filter
|
|
9
|
+
|
|
10
|
+
client = HouyiClient("http://127.0.0.1:7000")
|
|
11
|
+
col = client.collection("goods") # 首次 upsert 时隐式创建
|
|
12
|
+
|
|
13
|
+
col.upsert([
|
|
14
|
+
Vector(id=1, values=[0.9, 0.1], payload={"name": "apple", "price": 3.5}),
|
|
15
|
+
Vector(id=2, values=[0.1, 0.9], payload={"name": "laptop", "price": 8999}),
|
|
16
|
+
])
|
|
17
|
+
|
|
18
|
+
res = col.hybrid_search(
|
|
19
|
+
[0.85, 0.15], k=3,
|
|
20
|
+
filters=[Filter("price", "lt", 1000)],
|
|
21
|
+
include_payload=True,
|
|
22
|
+
)
|
|
23
|
+
for hit in res.hits:
|
|
24
|
+
print(hit.id, hit.score, hit.payload)
|
|
25
|
+
|
|
26
|
+
col.delete([1]) # 按 id
|
|
27
|
+
col.delete(filters=[Filter("price", "lt", 100)]) # 按条件(标量页求值,刚写入即可命中)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 契约要点
|
|
31
|
+
|
|
32
|
+
- **相似度分数**:`1 - cosine_distance`,越大越相似(余弦后端)。
|
|
33
|
+
- **过滤算子**:`eq` / `gt` / `lt` / `gte` / `lte` / `in`,多条取交集。
|
|
34
|
+
- **保留键**:payload 不得使用 `label` 键(400),label 走顶层字段。
|
|
35
|
+
- **id 空间**:u64;`houyidb.stable_id(str)` 可把字符串 id 确定性映射进 u64。
|
|
36
|
+
- **v1 易失性**:collection 的 payload/标量页不写 WAL,进程重启后丢失(向量索引不受影响)。
|
|
37
|
+
- **错误**:非 2xx 一律抛 `HouyiError(status_code, message)`。
|
|
38
|
+
|
|
39
|
+
## 生态 adapter
|
|
40
|
+
|
|
41
|
+
- `langchain-houyidb` — LangChain `VectorStore` 实现
|
|
42
|
+
- `llama-index-vector-stores-houyidb` — LlamaIndex `BasePydanticVectorStore` 实现
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""HouyiDB Python SDK — collections HTTP API 的薄封装。
|
|
2
|
+
|
|
3
|
+
只封装传输与类型:collection 路由、upsert/search/hybrid_search/delete、
|
|
4
|
+
响应数据类化。框架语义(Document、filter DSL、embedding 职责)不属于本层,
|
|
5
|
+
由 langchain-houyidb / llama-index-vector-stores-houyidb 等 adapter 承担。
|
|
6
|
+
|
|
7
|
+
EN: Thin wrapper over the collections HTTP API. This layer only covers
|
|
8
|
+
transport and types: collection routes, upsert/search/hybrid_search/delete,
|
|
9
|
+
and response dataclasses. Framework semantics (Document, filter DSL, embedding
|
|
10
|
+
responsibilities) belong to the adapters such as langchain-houyidb /
|
|
11
|
+
llama-index-vector-stores-houyidb.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from .client import (
|
|
15
|
+
Collection,
|
|
16
|
+
Filter,
|
|
17
|
+
HouyiClient,
|
|
18
|
+
HouyiError,
|
|
19
|
+
SearchHit,
|
|
20
|
+
SearchResult,
|
|
21
|
+
Vector,
|
|
22
|
+
stable_id,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"Collection",
|
|
27
|
+
"Filter",
|
|
28
|
+
"HouyiClient",
|
|
29
|
+
"HouyiError",
|
|
30
|
+
"SearchHit",
|
|
31
|
+
"SearchResult",
|
|
32
|
+
"Vector",
|
|
33
|
+
"stable_id",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
__version__ = "0.2.0b5"
|
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
"""HouyiDB collections HTTP API 客户端。
|
|
2
|
+
|
|
3
|
+
设计约束(与服务端契约一一对应):
|
|
4
|
+
|
|
5
|
+
- collection 在首次 upsert 时隐式创建,维度由首个向量定型;
|
|
6
|
+
- payload 键 ``label`` 为保留列,占用会 400(用顶层 ``label`` 字段);
|
|
7
|
+
- 检索响应的 ``score`` 是相似度(``1 - cosine_distance``,越大越相似);
|
|
8
|
+
- ``include_payload=True`` 时响应携带每命中的 label+payload(键为 id 字符串);
|
|
9
|
+
- delete 按 id 幂等删除,返回真实删除数;
|
|
10
|
+
- collection 的标量页 v1 易失(进程重启后 payload/过滤失效,向量索引不受影响)。
|
|
11
|
+
|
|
12
|
+
EN: HouyiDB collections HTTP API client. The design constraints mirror the
|
|
13
|
+
server contract one-to-one:
|
|
14
|
+
|
|
15
|
+
- collections are created implicitly on first upsert; dimensions are fixed by
|
|
16
|
+
the first vector;
|
|
17
|
+
- the ``label`` payload key is a reserved column; using it returns 400 (use the
|
|
18
|
+
top-level ``label`` field instead);
|
|
19
|
+
- ``score`` in search responses is similarity (``1 - cosine_distance``, larger
|
|
20
|
+
is more similar);
|
|
21
|
+
- with ``include_payload=True`` each hit carries label+payload (keyed by id
|
|
22
|
+
string);
|
|
23
|
+
- delete is idempotent by id and returns the number actually deleted;
|
|
24
|
+
- the collection scalar page in v1 is volatile (payload/filters are lost after
|
|
25
|
+
a restart; the vector index is unaffected).
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
from urllib.parse import quote
|
|
31
|
+
|
|
32
|
+
import hashlib
|
|
33
|
+
from dataclasses import dataclass, field
|
|
34
|
+
from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
|
|
35
|
+
|
|
36
|
+
import requests
|
|
37
|
+
|
|
38
|
+
#: u64 正整数键空间的上半位留空(与服务端 u64 id 对齐,避免符号位歧义)。
|
|
39
|
+
#: EN: Leave the upper half of the u64 key space unused (aligned with the
|
|
40
|
+
#: server's u64 ids to avoid sign-bit ambiguity).
|
|
41
|
+
_U64_MASK = (1 << 63) - 1
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def stable_id(text: str) -> int:
|
|
45
|
+
"""把任意字符串 id 确定性映射为 HouyiDB 的 u64 向量 id。
|
|
46
|
+
|
|
47
|
+
adapter 层共用:langchain 的 str ids、llama-index 的 node_id 都经此函数
|
|
48
|
+
落到 u64 键空间;同一输入恒得同一输出,因此 delete(ids) 可以重放同一映射。
|
|
49
|
+
|
|
50
|
+
EN: Deterministically map an arbitrary string id to a HouyiDB u64 vector
|
|
51
|
+
id. Shared by the adapters: LangChain str ids and LlamaIndex node_ids land
|
|
52
|
+
in the u64 key space through this function; the same input always yields
|
|
53
|
+
the same output, so delete(ids) can replay the same mapping.
|
|
54
|
+
"""
|
|
55
|
+
digest = hashlib.blake2b(text.encode("utf-8"), digest_size=8).digest()
|
|
56
|
+
return int.from_bytes(digest, "big") & _U64_MASK
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class HouyiError(Exception):
|
|
60
|
+
"""服务端返回的非 2xx 响应(status_code + 服务端诊断文本)。
|
|
61
|
+
|
|
62
|
+
EN: Non-2xx response from the server (status_code + server diagnostic text).
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
def __init__(self, status_code: int, message: str):
|
|
66
|
+
self.status_code = status_code
|
|
67
|
+
super().__init__(f"houyidb HTTP {status_code}: {message}")
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass
|
|
71
|
+
class Vector:
|
|
72
|
+
"""一条待写入向量:id + 分量 + 可选 label/payload。
|
|
73
|
+
|
|
74
|
+
EN: A vector to write: id + components + optional label/payload.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
id: int
|
|
78
|
+
values: Sequence[float]
|
|
79
|
+
label: Optional[str] = None
|
|
80
|
+
payload: Optional[Mapping[str, Any]] = None
|
|
81
|
+
|
|
82
|
+
def to_json(self) -> Dict[str, Any]:
|
|
83
|
+
doc: Dict[str, Any] = {"id": self.id, "values": list(self.values)}
|
|
84
|
+
if self.label is not None:
|
|
85
|
+
doc["label"] = self.label
|
|
86
|
+
if self.payload:
|
|
87
|
+
doc["payload"] = dict(self.payload)
|
|
88
|
+
return doc
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@dataclass
|
|
92
|
+
class Filter:
|
|
93
|
+
"""一条结构化过滤条件(多条之间取交集)。
|
|
94
|
+
|
|
95
|
+
op 白名单与服务端一致:``eq`` / ``gt`` / ``lt`` / ``gte`` / ``lte`` / ``in``。
|
|
96
|
+
|
|
97
|
+
EN: A structured filter condition (multiple conditions intersect). The op
|
|
98
|
+
whitelist matches the server: ``eq`` / ``gt`` / ``lt`` / ``gte`` / ``lte``
|
|
99
|
+
/ ``in``.
|
|
100
|
+
"""
|
|
101
|
+
|
|
102
|
+
column: str
|
|
103
|
+
op: str
|
|
104
|
+
value: Any
|
|
105
|
+
|
|
106
|
+
def to_json(self) -> Dict[str, Any]:
|
|
107
|
+
return {"column": self.column, "op": self.op, "value": self.value}
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
@dataclass
|
|
111
|
+
class SearchHit:
|
|
112
|
+
"""单条命中:id + 相似度分数 + 可选 payload(include_payload 时)。
|
|
113
|
+
|
|
114
|
+
EN: A single hit: id + similarity score + optional payload (with
|
|
115
|
+
include_payload).
|
|
116
|
+
"""
|
|
117
|
+
|
|
118
|
+
id: int
|
|
119
|
+
score: float
|
|
120
|
+
payload: Optional[Dict[str, Any]] = None
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
@dataclass
|
|
124
|
+
class SearchResult:
|
|
125
|
+
"""检索响应的数据类化:hits 按相似度从高到低排列。
|
|
126
|
+
|
|
127
|
+
EN: Typed search response: hits ordered by similarity, highest first.
|
|
128
|
+
"""
|
|
129
|
+
|
|
130
|
+
hits: List[SearchHit] = field(default_factory=list)
|
|
131
|
+
|
|
132
|
+
@property
|
|
133
|
+
def ids(self) -> List[int]:
|
|
134
|
+
return [h.id for h in self.hits]
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def scores(self) -> List[float]:
|
|
138
|
+
return [h.score for h in self.hits]
|
|
139
|
+
|
|
140
|
+
@classmethod
|
|
141
|
+
def from_json(cls, body: Mapping[str, Any]) -> "SearchResult":
|
|
142
|
+
ids: Sequence[int] = body.get("ids", [])
|
|
143
|
+
scores: Sequence[float] = body.get("scores", [])
|
|
144
|
+
payloads: Optional[Mapping[str, Any]] = body.get("payloads")
|
|
145
|
+
hits = [
|
|
146
|
+
SearchHit(
|
|
147
|
+
id=i,
|
|
148
|
+
score=s,
|
|
149
|
+
payload=dict(payloads[str(i)]) if payloads and str(i) in payloads else None,
|
|
150
|
+
)
|
|
151
|
+
for i, s in zip(ids, scores)
|
|
152
|
+
]
|
|
153
|
+
return cls(hits=hits)
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class Collection:
|
|
157
|
+
"""一个 named collection 的操作句柄(经 :class:`HouyiClient.collection` 获取)。
|
|
158
|
+
|
|
159
|
+
EN: Operation handle for one named collection (obtained via
|
|
160
|
+
:class:`HouyiClient.collection`).
|
|
161
|
+
"""
|
|
162
|
+
|
|
163
|
+
def __init__(self, client: "HouyiClient", name: str):
|
|
164
|
+
self._client = client
|
|
165
|
+
self.name = name
|
|
166
|
+
# URL 路径段必须转义:`requests` 原样保留 `/`/`?`/`#`——含这些字符的名字
|
|
167
|
+
# 会改写路由结构,表现为莫名其妙的 404 且 collection 永远建不出来。
|
|
168
|
+
# EN: The URL path segment must be escaped: `requests` keeps `/`, `?`,
|
|
169
|
+
# and `#` as-is — names containing them rewrite the route structure,
|
|
170
|
+
# showing up as baffling 404s and a collection that can never be created.
|
|
171
|
+
self._quoted = quote(name, safe="")
|
|
172
|
+
|
|
173
|
+
def upsert(self, vectors: Iterable[Vector | Mapping[str, Any]]) -> int:
|
|
174
|
+
"""写入一批向量(collection 首次写入时隐式创建)。返回插入条数。
|
|
175
|
+
|
|
176
|
+
EN: Write a batch of vectors (the collection is created implicitly on
|
|
177
|
+
the first write). Returns the number of inserted rows.
|
|
178
|
+
"""
|
|
179
|
+
docs = [v.to_json() if isinstance(v, Vector) else dict(v) for v in vectors]
|
|
180
|
+
body = self._client._post(f"/v1/collections/{self._quoted}/upsert", {"vectors": docs})
|
|
181
|
+
return int(body["inserted"])
|
|
182
|
+
|
|
183
|
+
def search(
|
|
184
|
+
self,
|
|
185
|
+
vector: Sequence[float],
|
|
186
|
+
k: int,
|
|
187
|
+
*,
|
|
188
|
+
ef_search: Optional[int] = None,
|
|
189
|
+
include_payload: bool = False,
|
|
190
|
+
) -> SearchResult:
|
|
191
|
+
"""纯向量 top-k 检索。
|
|
192
|
+
|
|
193
|
+
EN: Pure vector top-k search.
|
|
194
|
+
"""
|
|
195
|
+
req: Dict[str, Any] = {"vector": list(vector), "k": k}
|
|
196
|
+
if ef_search is not None:
|
|
197
|
+
req["ef_search"] = ef_search
|
|
198
|
+
if include_payload:
|
|
199
|
+
req["include_payload"] = True
|
|
200
|
+
body = self._client._post(f"/v1/collections/{self._quoted}/search", req)
|
|
201
|
+
return SearchResult.from_json(body)
|
|
202
|
+
|
|
203
|
+
def hybrid_search(
|
|
204
|
+
self,
|
|
205
|
+
vector: Sequence[float],
|
|
206
|
+
k: int,
|
|
207
|
+
*,
|
|
208
|
+
filters: Optional[Iterable[Filter | Mapping[str, Any]]] = None,
|
|
209
|
+
ef_search: Optional[int] = None,
|
|
210
|
+
include_payload: bool = False,
|
|
211
|
+
) -> SearchResult:
|
|
212
|
+
"""向量 × 标量过滤的混合检索(filters 取交集,仅 hnsw/flat 后端支持)。
|
|
213
|
+
|
|
214
|
+
EN: Hybrid vector x scalar-filter search (filters intersect; only the
|
|
215
|
+
hnsw/flat backends support this).
|
|
216
|
+
"""
|
|
217
|
+
req: Dict[str, Any] = {"vector": list(vector), "k": k}
|
|
218
|
+
if filters:
|
|
219
|
+
req["filters"] = [
|
|
220
|
+
f.to_json() if isinstance(f, Filter) else dict(f) for f in filters
|
|
221
|
+
]
|
|
222
|
+
if ef_search is not None:
|
|
223
|
+
req["ef_search"] = ef_search
|
|
224
|
+
if include_payload:
|
|
225
|
+
req["include_payload"] = True
|
|
226
|
+
body = self._client._post(f"/v1/collections/{self._quoted}/hybrid/search", req)
|
|
227
|
+
return SearchResult.from_json(body)
|
|
228
|
+
|
|
229
|
+
def delete(
|
|
230
|
+
self,
|
|
231
|
+
ids: Optional[Iterable[int]] = None,
|
|
232
|
+
*,
|
|
233
|
+
filters: Optional[Iterable[Filter | Mapping[str, Any]]] = None,
|
|
234
|
+
) -> int:
|
|
235
|
+
"""按 id 和/或过滤条件删除(幂等;两者取并集)。返回真实删除数。
|
|
236
|
+
|
|
237
|
+
按条件删除由服务端在标量页上求值:标量行随 upsert 同步落页,因此
|
|
238
|
+
刚写入、尚在异步构图队列中的向量也能被命中删除——这是「先检索拿 id
|
|
239
|
+
再删」无法保证的(检索在队列排空前看不到新写入)。
|
|
240
|
+
|
|
241
|
+
EN: Delete by id and/or filters (idempotent; the two sets are unioned).
|
|
242
|
+
Returns the number of rows actually deleted.
|
|
243
|
+
|
|
244
|
+
Filter deletion is evaluated by the server on the scalar page: scalar
|
|
245
|
+
rows land on the page synchronously with upsert, so vectors that were
|
|
246
|
+
just written and are still in the async build queue can be matched and
|
|
247
|
+
deleted — something "search for ids, then delete" cannot guarantee
|
|
248
|
+
(search does not see new writes until the queue drains).
|
|
249
|
+
"""
|
|
250
|
+
id_list = [int(i) for i in ids] if ids is not None else []
|
|
251
|
+
filter_list = (
|
|
252
|
+
[f.to_json() if isinstance(f, Filter) else dict(f) for f in filters]
|
|
253
|
+
if filters
|
|
254
|
+
else []
|
|
255
|
+
)
|
|
256
|
+
if not id_list and not filter_list:
|
|
257
|
+
raise ValueError("delete requires at least one of ids or filters")
|
|
258
|
+
body = self._client._post(
|
|
259
|
+
f"/v1/collections/{self._quoted}/delete",
|
|
260
|
+
{"ids": id_list, "filters": filter_list},
|
|
261
|
+
)
|
|
262
|
+
return int(body["deleted"])
|
|
263
|
+
|
|
264
|
+
def status(self) -> Dict[str, Any]:
|
|
265
|
+
"""collection 状态(indexed/pending/dims/index_type/scalar_row_count)。
|
|
266
|
+
|
|
267
|
+
EN: Collection status (indexed/pending/dims/index_type/scalar_row_count).
|
|
268
|
+
"""
|
|
269
|
+
return self._client._get(f"/v1/collections/{self._quoted}/status")
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
class HouyiClient:
|
|
273
|
+
"""HouyiDB 客户端入口。
|
|
274
|
+
|
|
275
|
+
:param base_url: 服务地址,如 ``http://127.0.0.1:7000``。
|
|
276
|
+
:param timeout: 单次请求超时秒数(连接+读取)。
|
|
277
|
+
:param session: 可选的 ``requests.Session``(连接池复用/自定义适配器)。
|
|
278
|
+
|
|
279
|
+
EN: HouyiDB client entry point.
|
|
280
|
+
|
|
281
|
+
:param base_url: Server address, e.g. ``http://127.0.0.1:7000``.
|
|
282
|
+
:param timeout: Per-request timeout in seconds (connect + read).
|
|
283
|
+
:param session: Optional ``requests.Session`` (connection pooling/custom
|
|
284
|
+
adapters).
|
|
285
|
+
"""
|
|
286
|
+
|
|
287
|
+
def __init__(
|
|
288
|
+
self,
|
|
289
|
+
base_url: str = "http://127.0.0.1:7000",
|
|
290
|
+
*,
|
|
291
|
+
timeout: float = 30.0,
|
|
292
|
+
session: Optional[requests.Session] = None,
|
|
293
|
+
):
|
|
294
|
+
self._base_url = base_url.rstrip("/")
|
|
295
|
+
self._timeout = timeout
|
|
296
|
+
self._session = session or requests.Session()
|
|
297
|
+
|
|
298
|
+
def collection(self, name: str) -> Collection:
|
|
299
|
+
return Collection(self, name)
|
|
300
|
+
|
|
301
|
+
def health(self) -> bool:
|
|
302
|
+
try:
|
|
303
|
+
body = self._get("/v1/health")
|
|
304
|
+
except (HouyiError, requests.RequestException):
|
|
305
|
+
return False
|
|
306
|
+
return body.get("status") == "ok"
|
|
307
|
+
|
|
308
|
+
def list_collections(self) -> List[Dict[str, Any]]:
|
|
309
|
+
return list(self._get("/v1/collections"))
|
|
310
|
+
|
|
311
|
+
def index_status(self) -> Dict[str, Any]:
|
|
312
|
+
"""主索引双速写入指标(hot/pending/flush_count 等,可观测性用)。
|
|
313
|
+
|
|
314
|
+
EN: Primary index dual-speed write metrics (hot/pending/flush_count,
|
|
315
|
+
etc.; for observability).
|
|
316
|
+
"""
|
|
317
|
+
return self._get("/v1/index/status")
|
|
318
|
+
|
|
319
|
+
# ── 内部传输 ──────────────────────────────────────────
|
|
320
|
+
# EN: Internal transport.
|
|
321
|
+
|
|
322
|
+
def _get(self, path: str) -> Any:
|
|
323
|
+
resp = self._session.get(f"{self._base_url}{path}", timeout=self._timeout)
|
|
324
|
+
return self._checked(resp)
|
|
325
|
+
|
|
326
|
+
def _post(self, path: str, payload: Mapping[str, Any]) -> Any:
|
|
327
|
+
resp = self._session.post(
|
|
328
|
+
f"{self._base_url}{path}", json=payload, timeout=self._timeout
|
|
329
|
+
)
|
|
330
|
+
return self._checked(resp)
|
|
331
|
+
|
|
332
|
+
@staticmethod
|
|
333
|
+
def _checked(resp: requests.Response) -> Any:
|
|
334
|
+
if resp.status_code >= 400:
|
|
335
|
+
# 服务端错误体是纯文本诊断(axum 元组错误),原样透出。
|
|
336
|
+
# EN: The server error body is a plain-text diagnostic (axum tuple
|
|
337
|
+
# error); surface it verbatim.
|
|
338
|
+
raise HouyiError(resp.status_code, resp.text.strip() or resp.reason)
|
|
339
|
+
return resp.json()
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: houyidb
|
|
3
|
+
Version: 0.2.0b5
|
|
4
|
+
Summary: Python SDK for HouyiDB — single-node vector database (collections HTTP API)
|
|
5
|
+
Author: HouyiDB Contributors
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://houyidb.top
|
|
8
|
+
Project-URL: Repository, https://github.com/houyidb-community/houyidb
|
|
9
|
+
Project-URL: Documentation, https://github.com/houyidb-community/houyidb/blob/main/docs/USER_MANUAL.md
|
|
10
|
+
Keywords: vector-database,hnsw,rag,houyidb
|
|
11
|
+
Requires-Python: >=3.9
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
Requires-Dist: requests>=2.28
|
|
14
|
+
|
|
15
|
+
# houyidb — HouyiDB Python SDK
|
|
16
|
+
|
|
17
|
+
> [English](README.en.md)
|
|
18
|
+
|
|
19
|
+
HouyiDB collections HTTP API 的薄封装:传输 + 类型,不含框架语义。
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
from houyidb import HouyiClient, Vector, Filter
|
|
23
|
+
|
|
24
|
+
client = HouyiClient("http://127.0.0.1:7000")
|
|
25
|
+
col = client.collection("goods") # 首次 upsert 时隐式创建
|
|
26
|
+
|
|
27
|
+
col.upsert([
|
|
28
|
+
Vector(id=1, values=[0.9, 0.1], payload={"name": "apple", "price": 3.5}),
|
|
29
|
+
Vector(id=2, values=[0.1, 0.9], payload={"name": "laptop", "price": 8999}),
|
|
30
|
+
])
|
|
31
|
+
|
|
32
|
+
res = col.hybrid_search(
|
|
33
|
+
[0.85, 0.15], k=3,
|
|
34
|
+
filters=[Filter("price", "lt", 1000)],
|
|
35
|
+
include_payload=True,
|
|
36
|
+
)
|
|
37
|
+
for hit in res.hits:
|
|
38
|
+
print(hit.id, hit.score, hit.payload)
|
|
39
|
+
|
|
40
|
+
col.delete([1]) # 按 id
|
|
41
|
+
col.delete(filters=[Filter("price", "lt", 100)]) # 按条件(标量页求值,刚写入即可命中)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## 契约要点
|
|
45
|
+
|
|
46
|
+
- **相似度分数**:`1 - cosine_distance`,越大越相似(余弦后端)。
|
|
47
|
+
- **过滤算子**:`eq` / `gt` / `lt` / `gte` / `lte` / `in`,多条取交集。
|
|
48
|
+
- **保留键**:payload 不得使用 `label` 键(400),label 走顶层字段。
|
|
49
|
+
- **id 空间**:u64;`houyidb.stable_id(str)` 可把字符串 id 确定性映射进 u64。
|
|
50
|
+
- **v1 易失性**:collection 的 payload/标量页不写 WAL,进程重启后丢失(向量索引不受影响)。
|
|
51
|
+
- **错误**:非 2xx 一律抛 `HouyiError(status_code, message)`。
|
|
52
|
+
|
|
53
|
+
## 生态 adapter
|
|
54
|
+
|
|
55
|
+
- `langchain-houyidb` — LangChain `VectorStore` 实现
|
|
56
|
+
- `llama-index-vector-stores-houyidb` — LlamaIndex `BasePydanticVectorStore` 实现
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
requests>=2.28
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
houyidb
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "houyidb"
|
|
7
|
+
version = "0.2.0b5"
|
|
8
|
+
description = "Python SDK for HouyiDB — single-node vector database (collections HTTP API)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "Apache-2.0"
|
|
12
|
+
authors = [{ name = "HouyiDB Contributors" }]
|
|
13
|
+
keywords = ["vector-database", "hnsw", "rag", "houyidb"]
|
|
14
|
+
dependencies = ["requests>=2.28"]
|
|
15
|
+
|
|
16
|
+
[project.urls]
|
|
17
|
+
Homepage = "https://houyidb.top"
|
|
18
|
+
Repository = "https://github.com/houyidb-community/houyidb"
|
|
19
|
+
Documentation = "https://github.com/houyidb-community/houyidb/blob/main/docs/USER_MANUAL.md"
|
|
20
|
+
|
|
21
|
+
[tool.setuptools.packages.find]
|
|
22
|
+
include = ["houyidb*"]
|