docs(comments): 注释中文化 · internal/runtime/memory(31 文件,纯替换)
- 只翻注释/文档字符串:820 增 / 820 删 严格 1:1;剥掉整行注释与行尾注释尾巴后, 逐文件与 HEAD 比对「代码部分差异 = 0」;裁决/design 编号计数逐项与 HEAD 一致 - 保留可执行 SQL 样例、SQLite 报错原文、pgvector/HNSW/ANN/BLOB 等技术词原文 - 复核:go build 绿 + memory/projectindex/vector 三包测试绿;gofmt 仅剩 2 个既有未格式化文件(改动前即如此,未顺手修)
This commit is contained in:
1 parent
eb1828ee7a
commit
61cf80d5ee
31 files changed
+820
-820
No files matched your search
@@ -13,11 +13,11 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/embedding"
|
||||
)
|
||||
|
||||
// createVecItemsTable is the idempotent SQLite schema. vector is stored as a
|
||||
// BLOB of little-endian float32 values; dim records the dimension so the blob
|
||||
// can be decoded without external knowledge. The table is created by
|
||||
// NewSQLite; migration compatibility with internal/db is not required because
|
||||
// the vector store is self-contained (see internal/runtime/memory/store.go).
|
||||
// createVecItemsTable 是幂等的 SQLite schema。vector 以小端
|
||||
// float32 值的 BLOB 存储;dim 记录维度,因此 blob
|
||||
// 无需外部信息即可解码。该表由
|
||||
// NewSQLite 创建;不要求与 internal/db 的迁移兼容,因为
|
||||
// 向量存储是自包含的(见 internal/runtime/memory/store.go)。
|
||||
const createVecItemsTable = `
|
||||
CREATE TABLE IF NOT EXISTS vec_items (
|
||||
id TEXT PRIMARY KEY,
|
||||
@@ -25,13 +25,13 @@ CREATE TABLE IF NOT EXISTS vec_items (
|
||||
dim INTEGER NOT NULL
|
||||
)`
|
||||
|
||||
// SQLiteIndex stores vectors as BLOBs in a SQLite vec_items table and answers
|
||||
// similarity with Go-side cosine similarity over a linear scan (milestone M4
|
||||
// semantics: small datasets, no ANN index).
|
||||
// SQLiteIndex 把向量以 BLOB 存入 SQLite 的 vec_items 表,并以
|
||||
// Go 侧线性扫描的余弦相似度作答相似度(M4 里程碑
|
||||
// 语义:小数据集,无 ANN 索引)。
|
||||
//
|
||||
// Concurrency is delegated to the *sql.DB, which is safe for concurrent use by
|
||||
// contract, so SQLiteIndex holds no further lock. Every query is parameterized
|
||||
// (?) and columns are listed explicitly.
|
||||
// 并发交由 *sql.DB,按约定它可安全并发使用,
|
||||
// 因此 SQLiteIndex 不再持锁。每个查询都参数化
|
||||
// (?)且列清单显式列出。
|
||||
type SQLiteIndex struct {
|
||||
db *sql.DB
|
||||
dim int
|
||||
@@ -39,14 +39,14 @@ type SQLiteIndex struct {
|
||||
log *slog.Logger
|
||||
}
|
||||
|
||||
// NewSQLite builds a SQLiteIndex on db for vectors of dimension dim, ensuring
|
||||
// the vec_items schema exists. db must be a live connection; a nil db returns
|
||||
// ErrNilDB, and a non-positive dim returns ErrInvalidDim. ctx controls schema
|
||||
// creation. log may be nil.
|
||||
// NewSQLite 在 db 上为维度 dim 的向量构建 SQLiteIndex,确保
|
||||
// vec_items schema 存在。db 必须是存活连接;nil db 返回
|
||||
// ErrNilDB,dim 非正返回 ErrInvalidDim。ctx 控制 schema
|
||||
// 创建。log 可为 nil。
|
||||
//
|
||||
// The returned index has no embedder wired in, so calling Embed directly
|
||||
// returns ErrNoEmbedder; use New to build a fully wired index, or wire one in
|
||||
// before calling Embed.
|
||||
// 返回的索引没有接入 embedder,因此直接调用 Embed
|
||||
// 会返回 ErrNoEmbedder;用 New 构建完全接好的索引,或在调用
|
||||
// Embed 前接入一个。
|
||||
func NewSQLite(ctx context.Context, db *sql.DB, dim int, log *slog.Logger) (*SQLiteIndex, error) {
|
||||
if db == nil {
|
||||
return nil, ErrNilDB
|
||||
@@ -62,16 +62,16 @@ func NewSQLite(ctx context.Context, db *sql.DB, dim int, log *slog.Logger) (*SQL
|
||||
return &SQLiteIndex{db: db, dim: dim, log: log}, nil
|
||||
}
|
||||
|
||||
// withEmbedder wires the vector-producing embedder into the index. It is used
|
||||
// by New; tests may also call it directly.
|
||||
// withEmbedder 把产向量的 embedder 接入索引。它由
|
||||
// New 使用;测试也可直接调用。
|
||||
func (s *SQLiteIndex) withEmbedder(e embedding.Embedder) { s.embedder = e }
|
||||
|
||||
// Dim returns the fixed vector dimension.
|
||||
// Dim 返回固定向量维度。
|
||||
func (s *SQLiteIndex) Dim() int { return s.dim }
|
||||
|
||||
// Embed turns texts into vectors with the wired embedder. It returns one Vector
|
||||
// per input text, aligned by index. With no embedder wired it returns
|
||||
// ErrNoEmbedder.
|
||||
// Embed 用接入的 embedder 把 texts 转成向量。每段输入文本
|
||||
// 对应一个按索引对齐的 Vector。未接入 embedder 时返回
|
||||
// ErrNoEmbedder。
|
||||
func (s *SQLiteIndex) Embed(ctx context.Context, texts []string) ([]Vector, error) {
|
||||
if s.embedder == nil {
|
||||
return nil, ErrNoEmbedder
|
||||
@@ -87,10 +87,10 @@ func (s *SQLiteIndex) Embed(ctx context.Context, texts []string) ([]Vector, erro
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Add persists the (id, vector) pair, upserting on a repeated id so the
|
||||
// latest vector wins. It rejects a blank id (ErrMissingID) and a vector whose
|
||||
// length differs from the index dimension (ErrDimMismatch). ctx aborts the
|
||||
// write when canceled.
|
||||
// Add 持久化 (id, vector) 对,id 重复时 upsert,
|
||||
// 最新的向量生效。它拒绝空 id(ErrMissingID)以及与
|
||||
// 索引维度不一致的向量(ErrDimMismatch)。ctx 被取消时
|
||||
// 中止写入。
|
||||
func (s *SQLiteIndex) Add(ctx context.Context, id string, v Vector) error {
|
||||
if strings.TrimSpace(id) == "" {
|
||||
return ErrMissingID
|
||||
@@ -108,10 +108,10 @@ func (s *SQLiteIndex) Add(ctx context.Context, id string, v Vector) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// Search returns up to topK ids most similar to q, ranked by descending cosine
|
||||
// similarity. It scans every persisted vector in Go (linear scan, no ANN). A
|
||||
// non-positive topK returns an empty result; a query whose length differs from
|
||||
// the index dimension returns ErrDimMismatch.
|
||||
// Search 返回与 q 最相似的最多 topK 个 id,按余弦相似度
|
||||
// 降序排列。它在 Go 侧扫描每个已持久化向量(线性扫描,无 ANN)。topK
|
||||
// 非正返回空结果;长度与
|
||||
// 索引维度不一致的查询返回 ErrDimMismatch。
|
||||
func (s *SQLiteIndex) Search(ctx context.Context, q Vector, topK int) ([]Hit, error) {
|
||||
if topK <= 0 {
|
||||
return []Hit{}, nil
|
||||
@@ -151,8 +151,8 @@ func (s *SQLiteIndex) Search(ctx context.Context, q Vector, topK int) ([]Hit, er
|
||||
return hits, nil
|
||||
}
|
||||
|
||||
// Close releases the underlying SQLite database. It is safe to call when the
|
||||
// database is already closed.
|
||||
// Close 释放底层的 SQLite 数据库。数据库
|
||||
// 已关闭时调用也是安全的。
|
||||
func (s *SQLiteIndex) Close() error {
|
||||
if s.db == nil {
|
||||
return nil
|
||||
@@ -164,7 +164,7 @@ func (s *SQLiteIndex) Close() error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// encodeVector serializes v to a little-endian float32 BLOB. It cannot fail.
|
||||
// encodeVector 把 v 序列化为小端 float32 BLOB。它不会失败。
|
||||
func encodeVector(v Vector) []byte {
|
||||
buf := make([]byte, 4*len(v))
|
||||
for i, x := range v {
|
||||
@@ -173,9 +173,9 @@ func encodeVector(v Vector) []byte {
|
||||
return buf
|
||||
}
|
||||
|
||||
// decodeVector deserializes a BLOB back into a Vector. It rejects empty or
|
||||
// non-4-byte-aligned blobs so a corrupted row surfaces as an error rather than
|
||||
// a silent misread.
|
||||
// decodeVector 把 BLOB 反序列化回 Vector。它拒绝空或
|
||||
// 非 4 字节对齐的 blob,使损坏的行以错误暴露,而不是
|
||||
// 被静默误读。
|
||||
func decodeVector(blob []byte) (Vector, error) {
|
||||
if len(blob) == 0 || len(blob)%4 != 0 {
|
||||
return nil, fmt.Errorf("memory/vector: invalid vector blob length %d", len(blob))
|
||||
@@ -187,9 +187,9 @@ func decodeVector(blob []byte) (Vector, error) {
|
||||
return v, nil
|
||||
}
|
||||
|
||||
// cosine returns the cosine similarity of a and b in [-1, 1]. Zero-length or
|
||||
// mismatched vectors yield 0, so an inconsistent stored row never corrupts the
|
||||
// ranking.
|
||||
// cosine 返回 a 与 b 的余弦相似度,取值 [-1, 1]。长度为零或
|
||||
// 不一致的向量得 0,因此不一致的存储行绝不会破坏
|
||||
// 排名。
|
||||
func cosine(a, b Vector) float64 {
|
||||
if len(a) == 0 || len(b) == 0 || len(a) != len(b) {
|
||||
return 0
|
||||
|
||||
Reference in new issue
Block a user