Hashgrid DNA (local)

hashgrid

Hashgrid DNA 的 Python 客户端。Hashgrid DNA 是一款能够从反馈中学习的搜索引擎。添加条目并搜索，然后为结果评分；DNA 会从评分中学习，让后续搜索的排序更好。

DNA 只处理嵌入向量，永远看不到你的内容。此软件包会在你的机器上嵌入文本和图像，只将向量发送给 DNA，并将内容保留在你的本地索引中。

pip install 'hashgrid[local]'

[local] 会添加本地嵌入器，它们在你的 CPU 上运行，无需账号。若要改用 OpenAI 或 Voyage 进行嵌入，请安装纯 hashgrid 并使用你自己的密钥。

每个网格都有自己的 API 密钥（hg-…）。创建网格无需密钥：

from hashgrid.dna import Grid

grid, api_key = Grid.create("mine")
print(api_key)   # shown only now: keep it, e.g. as $HASHGRID_API_KEY

以这种方式创建的网格最多可容纳 1024 个条目和查询（grid.dna.get_grid().max_nodes），每个地址每天可创建几个网格。需要更多？请联系 [email protected]。

添加、搜索、评分

from hashgrid.dna import Grid

grid = Grid()  # Index() and DNA(), from the environment: the key from $HASHGRID_API_KEY

grid.add_many({
    "/cities/lisbon": "Lisbon, a hilly coastal capital",
    "/cities/oslo": "Oslo, between fjords and forest",
})

query, results = grid.ask("a capital by the sea", k=2, prefix="/cities/")
results[0].content                    # "Lisbon, a hilly coastal capital"
grid.score(query, results[0], 1.0)    # a good result
grid.score(query, results[1], -0.5)   # a poor one

• 条目有一个 key，即网格中唯一的路径。搜索只能找到条目，prefix 会将搜索范围缩小到以该前缀开头的键。如果没有键，条目会以其内容的哈希值作为键，因此再次添加相同内容会返回同一个条目。
• 查询没有键。grid.search(query, k) 会返回接下来尚未显示过的 k 个结果。
• 评分范围从 -1（错误）到 1（完美）。你可以为结果评分，也可以为你已知好坏的任意一对内容评分。只有评分会用于训练 DNA。

每个 Result 都包含条目的 id、key、content（来自索引）和你的 score。grid.results(query) 会列出某个查询目前的结果，grid.get 和 grid.delete 接受条目或其 ID。 grid.delete_grid() 会永久删除整个网格及其在索引中的内容。AsyncGrid 执行相同的操作，但需使用 await。

图像

内容可以是文本，也可以是来自文件或字节的 Image。图像需要使用能够处理图像的嵌入器：

from hashgrid.dna import Grid
from hashgrid.index import Image, Index

grid = Grid(Index("fastembed:Qdrant/clip-ViT-B-32"))
grid.add(Image("photos/beach.jpg"), key="/photos/beach")
query, results = grid.ask("a sunny beach", k=5)      # text finds images
query, results = grid.ask(Image("another.jpg"))      # and so do images

索引

Index 是网格的本地部分。它会嵌入内容，并按 DNA ID 将内容保存在 sqlite 中，以便结果返回时包含其内容。Index() 使用默认嵌入器和 ~/.hashgrid/index.sqlite； $HASHGRID_EMBEDDER 和 $HASHGRID_INDEX 可以更改它们，也可以通过参数更改：

Index("voyage:voyage-multimodal-3")
Index(OpenAI("text-embedding-3-small", dimensions=512), path="my-index.sqlite")
Index(path=":memory:")   # keeps nothing

每个网格使用一个嵌入器。不同模型生成的向量不可比较。索引会记录每个网格使用的嵌入器，并拒绝使用其他嵌入器；网格也会拒绝长度与自身向量不同的向量。

嵌入器	接受内容	运行位置	需要
fastembed:BAAI/bge-small-en-v1.5（默认）	文本	本地	hashgrid[local]
fastembed:Qdrant/clip-ViT-B-32、fastembed:jinaai/jina-clip-v1	文本、图像	本地	hashgrid[local]
openai:text-embedding-3-small	文本	OpenAI	OPENAI_API_KEY
voyage:voyage-3.5	文本	Voyage AI	VOYAGE_API_KEY
voyage:voyage-multimodal-3	文本、图像	Voyage AI	VOYAGE_API_KEY

其他 fastembed、OpenAI 和 Voyage 模型也可使用：fastembed:<model>、openai:<model>、voyage:<model>。DNA 最多接受 2048 个值，因此 openai:text-embedding-3-large 会缩短为 2048（openai:<model>@<n> 可设置长度）。使用 OpenAI 或 Voyage 时，你的内容会通过你自己的密钥发送给相应提供方，但仍不会发送给 DNA。你自己的嵌入器可以是任何具有 spec、所接受的 modalities（{"text"}、{"text", "image"}）以及 embed(contents, kind) 的对象，其中 kind 为 "document" 或 "query"。

类型化 API

DNA 和 AsyncDNA 为 HTTP API 的每个路由各提供一个方法，方法名称与路由对应。

from hashgrid.dna import DNA

dna = DNA("hg-…")
item = dna.create_node([0.1, 0.2, 0.3], key="/items/1")
query = dna.create_node([0.1, 0.2, 0.25])
edge = dna.create_edge(query, prefix="/items/")   # the search; None when nothing is left
dna.put_edge(query, edge, 1.0)                    # the score

方法	路由
create_grid(name)、acreate_grid(name)（函数，无需密钥）	POST /
get_grid()	GET /
delete_grid()	DELETE /
list_nodes(cursor, limit)、iter_nodes()	GET /nodes
get_node(nid)	GET /nodes/{nid}
create_node(emb, key=None)	POST /nodes
update_node(nid, key=…, emb=…)	PATCH /nodes/{nid}
delete_node(nid)	DELETE /nodes/{nid}
list_edges(nid, cursor, limit)、iter_edges(nid)	GET /nodes/{nid}/edges
get_edge(nid, eid)	GET /nodes/{nid}/edges/{eid}
create_edge(nid, prefix="")，别名 search	POST /nodes/{nid}/edges
put_edge(nid, eid, score)，别名 score	PUT /nodes/{nid}/edges/{eid}
update_edge(nid, eid, score)	PATCH /nodes/{nid}/edges/{eid}
delete_edge(nid, eid)	DELETE /nodes/{nid}/edges/{eid}

ID 是 16 个字符的十六进制字符串。方法也可以接收 Node 或 Edge 本身。错误包括 Unauthorized（401）、Forbidden（403：网格已达到节点数量上限，或已被冻结）、NotFound（404）、Conflict（409，密钥已被占用）、Invalid（422）和 TooManyRequests（429：从你的地址创建的网格过多；请稍后再试），它们都是 DNAError 的子类。

MCP 服务

hashgrid-mcp 是一个通过 stdio 通信的本地 MCP 服务，供处理文本和图像的 Agent 使用。它在你的机器上生成嵌入，只向 DNA 发送向量，并将内容保留在本地索引中。

{
  "mcpServers": {
    "hashgrid": {
      "command": "uvx",
      "args": ["--from", "hashgrid[local]", "hashgrid-mcp"],
      "env": { "HASHGRID_API_KEY": "hg-…" }
    }
  }
}

使用 Claude Code：

claude mcp add hashgrid -e HASHGRID_API_KEY=hg-… -- uvx --from 'hashgrid[local]' hashgrid-mcp

没有密钥时，Agent 可以调用 create_grid：服务会创建一个网格，并将其密钥保存在本地索引中，之后便会使用该密钥。

工具：

• add_item(text | image, key?)：添加一项，可以是文本，也可以是图像文件的路径。
• search(query | image, k, prefix)：返回最佳结果及其文本或图像路径。
• more_results(query_id, k, prefix)：返回接下来的结果。
• score(query_id, item_id, score)：为结果评分。
• delete_item(item_id)：删除一项。
• create_grid(name)：服务没有密钥时创建网格。
• delete_grid(confirm)：永久删除网格；confirm 为网格名称。

首次调用时会下载本地模型，大小约为 70 MB。若要处理图像，请设置 HASHGRID_EMBEDDER=fastembed:Qdrant/clip-ViT-B-32。

变量	默认值
HASHGRID_API_KEY	create_grid 保存在索引中的密钥
HASHGRID_EMBEDDER	fastembed:BAAI/bge-small-en-v1.5；使用 openai:… 或 voyage:… 时，只需运行 uvx --from hashgrid hashgrid-mcp
HASHGRID_INDEX	~/.hashgrid/index.sqlite
HASHGRID_DNA_URL	https://dna.hashgrid.ai/api/v1

服务会在索引中记录每个网格使用的嵌入模型，并拒绝为同一网格使用其他模型。

托管服务 https://dna.hashgrid.ai/mcp 接收的是向量，而不是内容。如果你的 Agent 会自行生成嵌入，请使用该服务。

许可证

MIT