feat(provider): 完成阶段E协议适配、国内预设与模型路由
This commit is contained in:
@@ -22,6 +22,7 @@ from app.repository import BlockHit
|
||||
from app.retrieval.embedding import EmbeddingProvider, HashEmbeddingProvider
|
||||
from app.retrieval.hybrid import normalize_scores, rrf_fuse
|
||||
from app.retrieval.reranker import LexicalReranker, RankedCandidate, RerankerProvider
|
||||
from app.retrieval import routed_vectors
|
||||
from app.retrieval.vectorstore import SqliteVecStore, VectorStore
|
||||
from app.textutils import make_snippet, match_query
|
||||
|
||||
@@ -39,10 +40,15 @@ class RetrievalEngine:
|
||||
embedding: EmbeddingProvider,
|
||||
reranker: RerankerProvider,
|
||||
vector_store: VectorStore,
|
||||
*,
|
||||
route_embeddings: bool = False,
|
||||
) -> None:
|
||||
self.embedding = embedding
|
||||
self.reranker = reranker
|
||||
self.vector_store = vector_store
|
||||
# Only the production instance opts in. Replaced test dependencies must
|
||||
# remain authoritative, including monkeypatches on the singleton.
|
||||
self._routed_defaults = (embedding, vector_store) if route_embeddings else None
|
||||
|
||||
async def search(self, request: SearchRequest) -> SearchResponse:
|
||||
if request.mode == SearchMode.fts:
|
||||
@@ -74,8 +80,16 @@ class RetrievalEngine:
|
||||
fts_scores = {h.block_id: -h.bm25 for h in fts_hits}
|
||||
|
||||
if request.mode in (SearchMode.vector, SearchMode.hybrid):
|
||||
query_vec = await self.embedding.embed_query(request.query)
|
||||
vec_hits = await self.vector_store.search(query_vec, top_k=recall)
|
||||
vec_hits = None
|
||||
if (
|
||||
self._routed_defaults is not None
|
||||
and self.embedding is self._routed_defaults[0]
|
||||
and self.vector_store is self._routed_defaults[1]
|
||||
):
|
||||
vec_hits = await routed_vectors.search_remote(request.query, top_k=recall)
|
||||
if vec_hits is None:
|
||||
query_vec = await self.embedding.embed_query(request.query)
|
||||
vec_hits = await self.vector_store.search(query_vec, top_k=recall)
|
||||
vec_ranked = [v.id for v in vec_hits]
|
||||
vec_scores = {v.id: v.score for v in vec_hits}
|
||||
|
||||
@@ -217,4 +231,6 @@ def _utc(dt: datetime) -> datetime:
|
||||
|
||||
|
||||
# 默认引擎实例：轻量实现跑通链路，后续可替换真实模型实现
|
||||
engine = RetrievalEngine(HashEmbeddingProvider(), LexicalReranker(), SqliteVecStore())
|
||||
engine = RetrievalEngine(
|
||||
HashEmbeddingProvider(), LexicalReranker(), SqliteVecStore(), route_embeddings=True,
|
||||
)
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
"""Optional API embeddings, isolated from the stable hash/sqlite-vec index.
|
||||
|
||||
The runtime's model_id is the authoritative space ID (including provider URL,
|
||||
endpoint, model and dimensions); equal dimensions alone never imply compatibility.
|
||||
This phase uses a lazy, rebuildable SQLite side table instead of a schema migration.
|
||||
Search scans only current blocks in one database snapshot and requires complete
|
||||
coverage. Cosine ranking costs O(blocks * dimensions) with an O(top_k) heap; this
|
||||
small-vault implementation should become a per-space ANN index at larger scale.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import heapq
|
||||
import json
|
||||
import logging
|
||||
import math
|
||||
import sqlite3
|
||||
from dataclasses import dataclass
|
||||
from typing import Protocol
|
||||
|
||||
from app.database.db import connect, transaction
|
||||
from app.retrieval.vectorstore import VectorHit
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class EmbeddingResult(Protocol):
|
||||
vectors: list[list[float]]
|
||||
source: str
|
||||
model_id: str
|
||||
dimensions: int
|
||||
fallback_reason: str | None
|
||||
|
||||
|
||||
class EmbeddingRuntime(Protocol):
|
||||
async def embed(self, texts: list[str]) -> EmbeddingResult: ...
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RemoteEmbeddings:
|
||||
space_id: str
|
||||
dimensions: int
|
||||
vectors: list[list[float]]
|
||||
|
||||
|
||||
def get_model_routing() -> EmbeddingRuntime | None:
|
||||
"""Lazy integration hook; tests can inject a runtime without any network I/O."""
|
||||
from app.container import container
|
||||
|
||||
return getattr(container, "model_routing", None)
|
||||
|
||||
|
||||
def _unit_vector(vector: list[float], dimensions: int) -> list[float]:
|
||||
if len(vector) != dimensions:
|
||||
raise ValueError("embedding dimension mismatch")
|
||||
if any(isinstance(value, bool) or not isinstance(value, (int, float)) for value in vector):
|
||||
raise ValueError("embedding must be numeric")
|
||||
if not all(math.isfinite(value) for value in vector):
|
||||
raise ValueError("embedding must be finite")
|
||||
scale = max(abs(value) for value in vector)
|
||||
if scale == 0:
|
||||
raise ValueError("embedding must be nonzero")
|
||||
# Scaling first avoids overflow/underflow for finite but extreme API values.
|
||||
scaled = [value / scale for value in vector]
|
||||
norm = math.sqrt(math.fsum(value * value for value in scaled))
|
||||
return [value / norm for value in scaled]
|
||||
|
||||
|
||||
async def embed_remote(texts: list[str]) -> RemoteEmbeddings | None:
|
||||
"""Return validated API vectors, or None to use the caller's local baseline.
|
||||
|
||||
Do not use the runtime's local result: the caller may have injected its own
|
||||
embedding/store pair. Exception deliberately excludes cancellation.
|
||||
"""
|
||||
if not texts:
|
||||
return None
|
||||
try:
|
||||
runtime = get_model_routing()
|
||||
if runtime is None:
|
||||
return None
|
||||
result = await runtime.embed(texts)
|
||||
if result.source != "api":
|
||||
return None
|
||||
if not isinstance(result.model_id, str) or not result.model_id or result.model_id == "hash-v1":
|
||||
raise ValueError("API embedding needs a distinct space ID")
|
||||
if type(result.dimensions) is not int or result.dimensions <= 0:
|
||||
raise ValueError("invalid embedding dimensions")
|
||||
if len(result.vectors) != len(texts):
|
||||
raise ValueError("embedding count mismatch")
|
||||
return RemoteEmbeddings(
|
||||
space_id=result.model_id,
|
||||
dimensions=result.dimensions,
|
||||
vectors=[_unit_vector(vector, result.dimensions) for vector in result.vectors],
|
||||
)
|
||||
except Exception as exc:
|
||||
# Avoid logging provider exceptions containing credentials or note text.
|
||||
logger.warning("Remote embedding unavailable (%s); using local index", type(exc).__name__)
|
||||
return None
|
||||
|
||||
|
||||
def _ensure_table(conn: sqlite3.Connection) -> None:
|
||||
conn.execute("""
|
||||
CREATE TABLE IF NOT EXISTS routed_block_vectors (
|
||||
space_id TEXT NOT NULL,
|
||||
block_id TEXT NOT NULL REFERENCES blocks(block_id) ON DELETE CASCADE,
|
||||
dimensions INTEGER NOT NULL CHECK (dimensions > 0),
|
||||
vector TEXT NOT NULL,
|
||||
PRIMARY KEY (space_id, block_id)
|
||||
)
|
||||
""")
|
||||
conn.execute("""
|
||||
CREATE INDEX IF NOT EXISTS routed_block_vectors_block_id
|
||||
ON routed_block_vectors(block_id)
|
||||
""")
|
||||
|
||||
|
||||
def store_remote(
|
||||
conn: sqlite3.Connection, block_ids: list[str], batch: RemoteEmbeddings | None,
|
||||
) -> None:
|
||||
"""Best-effort side-index write inside the caller's metadata transaction.
|
||||
|
||||
A savepoint prevents partial remote batches and isolates storage failures from
|
||||
note saving. Replacing/deleting blocks cascades all old spaces automatically.
|
||||
"""
|
||||
if batch is None:
|
||||
return
|
||||
try:
|
||||
conn.execute("SAVEPOINT routed_vectors_write")
|
||||
try:
|
||||
if len(block_ids) != len(batch.vectors):
|
||||
raise ValueError("block/vector count mismatch")
|
||||
_ensure_table(conn)
|
||||
conn.executemany(
|
||||
"""INSERT INTO routed_block_vectors (space_id, block_id, dimensions, vector)
|
||||
VALUES (?, ?, ?, ?)
|
||||
ON CONFLICT (space_id, block_id) DO UPDATE SET
|
||||
dimensions = excluded.dimensions, vector = excluded.vector""",
|
||||
[
|
||||
(batch.space_id, block_id, batch.dimensions, json.dumps(vector, allow_nan=False))
|
||||
for block_id, vector in zip(block_ids, batch.vectors)
|
||||
],
|
||||
)
|
||||
except BaseException:
|
||||
conn.execute("ROLLBACK TO routed_vectors_write")
|
||||
raise
|
||||
finally:
|
||||
conn.execute("RELEASE routed_vectors_write")
|
||||
except Exception as exc:
|
||||
logger.warning("Remote vector storage unavailable (%s); local index retained", type(exc).__name__)
|
||||
|
||||
|
||||
async def search_remote(query: str, *, top_k: int) -> list[VectorHit] | None:
|
||||
"""None means fallback, including any missing/invalid current-block vector.
|
||||
|
||||
Read coverage and vectors together so concurrent note updates cannot produce
|
||||
an apparently complete subset. Never fill missing remote hits with local hits.
|
||||
"""
|
||||
batch = await embed_remote([query])
|
||||
if batch is None:
|
||||
return None
|
||||
try:
|
||||
conn = connect()
|
||||
try:
|
||||
with transaction(conn):
|
||||
exists = conn.execute(
|
||||
"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'routed_block_vectors'"
|
||||
).fetchone()
|
||||
if exists is None:
|
||||
return None
|
||||
rows = conn.execute(
|
||||
"""SELECT b.block_id, r.vector
|
||||
FROM blocks AS b
|
||||
LEFT JOIN routed_block_vectors AS r
|
||||
ON r.block_id = b.block_id AND r.space_id = ? AND r.dimensions = ?
|
||||
ORDER BY b.block_id""",
|
||||
(batch.space_id, batch.dimensions),
|
||||
)
|
||||
|
||||
def hits():
|
||||
for row in rows:
|
||||
if row["vector"] is None:
|
||||
raise ValueError("remote space has incomplete block coverage")
|
||||
vector = _unit_vector(json.loads(row["vector"]), batch.dimensions)
|
||||
score = math.fsum(a * b for a, b in zip(batch.vectors[0], vector))
|
||||
yield VectorHit(id=row["block_id"], score=max(0.0, min(1.0, score)))
|
||||
|
||||
return heapq.nlargest(top_k, hits(), key=lambda hit: hit.score)
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as exc:
|
||||
logger.debug("Remote vector search unavailable (%s); using local index", type(exc).__name__)
|
||||
return None
|
||||
Reference in New Issue
Block a user