docs(comments): 注释中文化 · internal/runtime/memory(31 文件,纯替换)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- 只翻注释/文档字符串: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:
AskaEth committed 2026-10-04 13:32:54 +08:00
1 parent eb1828ee7a
commit 61cf80d5ee
31 files changed
+820 -820

No files matched your search

+41 -41
View File
@@ -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