chore: 清理违反底座规则的死代码并修正接口文档编号
- 删除生产死代码 app/service/knowledge_tool_service.py 与 app/infrastructure/milvus_knowledge_adapter.py：后者硬编码 Milvus 字段名， 违反 AGENTS.md §E，且仅被前者引用；生产检索链路实际走 knowledge_search_tool -> KnowledgeSearchService -> knowledge_schema 运行时探测。 - 删除上述两模块的单测，以及依赖 legacy 位置参数构造的 tests/unit/service/test_knowledge_retrieval.py。 - app/service/knowledge_retrieval_service.py 整文件回退底座版本， 移除 legacy 双构造与重复检索实现。 - docs/05-接口文档.md：客服画像候选改登记为 §8.5，恢复 §8.2 解析知识引用； 既有 §8.1-§8.4 编号全部保持，修复此前出现两个 8.3 的问题。 - app/model/profile.py：current_customer_id 改为普通可空列映射，与 alembic/baseline_generated.sql 及真实库一致；原 Computed 声明会让 ORM 把该列 从 INSERT 中排除，与「必须显式写入」的实际 schema 不符。 - 新增 docs/客服Agent接入底座扩展说明_v1.md，供集成分支评审逐项确认。 验证：pytest tests/unit tests/contract -> 1275 passed, 2 skipped, 0 failed； ruff check app tests tools alembic 通过；mypy app 通过（244 个源文件）。
This commit is contained in:
张胜宇
@@ -1,74 +0,0 @@
|
||||
from typing import Any
|
||||
|
||||
from app.core.errors import ForbiddenAgentError, RecoverableAgentError
|
||||
from app.core.knowledge_contracts import ALLOWED_KNOWLEDGE_COLLECTIONS
|
||||
|
||||
|
||||
class MilvusKnowledgeClient:
|
||||
def __init__(self, uri: str, token: str | None = None) -> None:
|
||||
self._uri = uri
|
||||
self._token = token
|
||||
self._client: Any | None = None
|
||||
|
||||
async def _ensure_client(self) -> Any:
|
||||
if self._client is None:
|
||||
from pymilvus import AsyncMilvusClient # type: ignore[import-untyped]
|
||||
|
||||
self._client = AsyncMilvusClient(uri=self._uri, token=self._token)
|
||||
return self._client
|
||||
|
||||
async def search(
|
||||
self, collection: str, vector: list[float], top_k: int
|
||||
) -> list[dict[str, Any]]:
|
||||
if collection not in ALLOWED_KNOWLEDGE_COLLECTIONS:
|
||||
raise ForbiddenAgentError("未授权的知识集合")
|
||||
if len(vector) != 1024 or not 1 <= top_k <= 20:
|
||||
raise RecoverableAgentError("知识检索参数无效")
|
||||
try:
|
||||
client = await self._ensure_client()
|
||||
# Lite 重启后集合默认未加载；远程 Milvus 对重复加载保持幂等。
|
||||
load_collection = getattr(client, "load_collection", None)
|
||||
if load_collection is not None:
|
||||
await load_collection(collection_name=collection)
|
||||
batches = await client.search(
|
||||
collection_name=collection,
|
||||
data=[vector],
|
||||
limit=top_k,
|
||||
output_fields=["knowledge_id", "title", "snippet", "tags", "version"],
|
||||
search_params={"metric_type": "COSINE"},
|
||||
)
|
||||
except Exception as exc:
|
||||
raise RecoverableAgentError("知识检索不可用") from exc
|
||||
return [
|
||||
normalized
|
||||
for batch in batches
|
||||
for hit in batch
|
||||
if (normalized := self._normalize_hit(hit)) is not None
|
||||
]
|
||||
|
||||
@staticmethod
|
||||
def _normalize_hit(hit: Any) -> dict[str, Any] | None:
|
||||
"""统一 Milvus SDK 的平铺与 entity 包装命中格式。"""
|
||||
raw = dict(hit)
|
||||
entity = raw.get("entity")
|
||||
fields = entity if isinstance(entity, dict) else raw
|
||||
knowledge_id = fields.get("knowledge_id")
|
||||
snippet = fields.get("snippet")
|
||||
score = raw.get("score", raw.get("distance", fields.get("score")))
|
||||
if (
|
||||
not isinstance(knowledge_id, str)
|
||||
or not isinstance(snippet, str)
|
||||
or not isinstance(score, (int, float))
|
||||
or isinstance(score, bool)
|
||||
):
|
||||
return None
|
||||
normalized: dict[str, Any] = {
|
||||
"knowledge_id": knowledge_id,
|
||||
"snippet": snippet,
|
||||
"score": float(score),
|
||||
}
|
||||
for field in ("title", "tags", "version"):
|
||||
value = fields.get(field)
|
||||
if value is not None:
|
||||
normalized[field] = value
|
||||
return normalized
|
||||
@@ -4,15 +4,18 @@
|
||||
这里显式标注，避免后续有人按直觉写入而踩坑：
|
||||
|
||||
1. `user_facts.id` 在库里**没有 auto_increment**，插入时必须由应用显式提供主键；
|
||||
2. `profile_snapshots.current_customer_id` 是**生成列**（`IF(is_current=1, customer_id, NULL)`），
|
||||
与唯一键 `uk_profile_snapshot_current` 共同保证「每个客户最多一条当前快照」。生成列由数据库
|
||||
维护，因此这里只映射为只读计算列，写入时不会提供该字段。
|
||||
2. `profile_snapshots.current_customer_id` **不是生成列**，而是普通可空列 + 唯一键
|
||||
`uk_profile_snapshot_current`：当前版本必须由写入方**显式写入**客户 ID（历史版本写 NULL），
|
||||
才能保证「每个客户最多一条当前快照」。因此这里按普通可空列映射，**不能**声明 `Computed`——
|
||||
声明成生成列会让 SQLAlchemy 把它从 INSERT 中排除，反而永远写不进去。
|
||||
（`docs/00` 第 783 行把它描述为「生成列」，与实际 DDL 及真实库不一致；
|
||||
以 `alembic/baseline_generated.sql`、`tools/seed_profile_demo.py` 和真实库为准。）
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy import CHAR, JSON, BigInteger, Boolean, Computed, DateTime, Float, String
|
||||
from sqlalchemy import CHAR, JSON, BigInteger, Boolean, DateTime, Float, String
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.model.base import Base
|
||||
@@ -59,7 +62,5 @@ class ProfileSnapshot(Base):
|
||||
generated_at: Mapped[datetime | None] = mapped_column(DateTime)
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
|
||||
updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
|
||||
# 生成列由数据库维护；映射为只读计算列，便于按当前快照查询，不参与 INSERT/UPDATE。
|
||||
current_customer_id: Mapped[int | None] = mapped_column(
|
||||
BigInteger, Computed("IF(is_current = 1, customer_id, NULL)")
|
||||
)
|
||||
# 普通可空列 + 唯一键，由写入方显式赋值（见模块 docstring 第 2 条），不是生成列。
|
||||
current_customer_id: Mapped[int | None] = mapped_column(BigInteger)
|
||||
|
||||
@@ -113,25 +113,16 @@ class KnowledgeRetrievalService:
|
||||
def __init__(
|
||||
self,
|
||||
client: Any,
|
||||
*legacy_args: Any,
|
||||
*,
|
||||
embedder: Any = None,
|
||||
session_factory: Callable[[], Any] | None = None,
|
||||
config: KnowledgeRuntimeConfig | None = None,
|
||||
vector_dim: int = VECTOR_DIM,
|
||||
) -> None:
|
||||
# 兼容早期客服工具的 positional 构造：embedder, vector_store, config, authority。
|
||||
self._legacy = len(legacy_args) == 3
|
||||
if self._legacy:
|
||||
self.embedder = client
|
||||
self.client = legacy_args[0]
|
||||
self.config = legacy_args[1]
|
||||
self._authority = legacy_args[2]
|
||||
else:
|
||||
self.client = client
|
||||
self.embedder = embedder
|
||||
self.config = config or KnowledgeRuntimeConfig()
|
||||
self._authority = None
|
||||
self.client = client
|
||||
self.embedder = embedder
|
||||
self._session_factory: Callable[[], Any] = session_factory or SessionFactory
|
||||
self.config = config or KnowledgeRuntimeConfig()
|
||||
self.vector_dim = int(vector_dim)
|
||||
|
||||
# --- 入口 -----------------------------------------------------------------
|
||||
@@ -139,14 +130,11 @@ class KnowledgeRetrievalService:
|
||||
async def search(
|
||||
self,
|
||||
query: KnowledgeQuery,
|
||||
legacy_context: Any = None,
|
||||
*,
|
||||
embedding_endpoints: Sequence[Any] | None = None,
|
||||
embedder: Any = None,
|
||||
) -> KnowledgeSearchResult:
|
||||
"""执行检索。集合由意图映射，调用方无法指定集合名。"""
|
||||
if self._legacy:
|
||||
return await self._legacy_search(query)
|
||||
targets = self._assert_collections_allowed(query.intents)
|
||||
top_k = min(int(query.top_k), self.config.result_limit)
|
||||
searched = tuple(sorted({collection for collection, _ in targets}))
|
||||
@@ -162,49 +150,6 @@ class KnowledgeRetrievalService:
|
||||
hits = self._to_hits(verified)
|
||||
return KnowledgeSearchResult(hits=hits, degraded=False, searched_collections=searched)
|
||||
|
||||
async def _legacy_search(self, query: KnowledgeQuery) -> KnowledgeSearchResult:
|
||||
"""兼容旧工具调用，仍复用同一意图路由和 MySQL 权威回查。"""
|
||||
targets = self._assert_collections_allowed(query.intents)
|
||||
collections = tuple(sorted({collection for collection, _ in targets}))
|
||||
top_k = min(int(query.top_k), int(getattr(self.config, "result_limit", 20)))
|
||||
try:
|
||||
raw_vector = await self.embedder.embed(query.query)
|
||||
vector = self._vector_of(raw_vector)
|
||||
self.assert_vector_dim(vector)
|
||||
rows: list[dict[str, Any]] = []
|
||||
for collection, route_top_k in targets:
|
||||
rows.extend(await self.client.search(
|
||||
collection, vector, min(top_k, route_top_k)
|
||||
))
|
||||
if self._authority is not None:
|
||||
verified = await self._authority.filter_published(tuple(
|
||||
KnowledgeHit(
|
||||
knowledge_id=str(row.get("knowledge_id")),
|
||||
collection=collection,
|
||||
title=row.get("title"),
|
||||
snippet=str(row.get("snippet") or ""),
|
||||
score=self._score(row),
|
||||
)
|
||||
for row in rows
|
||||
for collection, _ in targets
|
||||
if str(row.get("collection") or collection) == collection
|
||||
))
|
||||
return KnowledgeSearchResult(
|
||||
hits=tuple(verified), searched_collections=collections
|
||||
)
|
||||
return KnowledgeSearchResult(hits=self._to_hits(rows), searched_collections=collections)
|
||||
except Exception:
|
||||
if self._authority is None:
|
||||
return KnowledgeSearchResult(
|
||||
hits=(), degraded=True, degradation_reason="milvus_unavailable",
|
||||
searched_collections=collections,
|
||||
)
|
||||
fallback = await self._authority.search_keyword(query, collections, top_k)
|
||||
return KnowledgeSearchResult(
|
||||
hits=tuple(fallback), degraded=True,
|
||||
degradation_reason="milvus_unavailable", searched_collections=collections,
|
||||
)
|
||||
|
||||
# --- 路由与白名单 ---------------------------------------------------------
|
||||
|
||||
def _assert_collections_allowed(
|
||||
@@ -257,8 +202,6 @@ class KnowledgeRetrievalService:
|
||||
|
||||
@staticmethod
|
||||
def _vector_of(execution: Any) -> list[float]:
|
||||
if isinstance(execution, list | tuple):
|
||||
return [float(item) for item in execution]
|
||||
raw = getattr(execution, "vector", None)
|
||||
if raw is None and isinstance(execution, Mapping):
|
||||
raw = execution.get("vector")
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
from typing import Protocol
|
||||
|
||||
from app.core.config import get_settings
|
||||
from app.core.contracts import RequestContext
|
||||
from app.core.knowledge_contracts import KnowledgeQuery, KnowledgeSearchResult
|
||||
from app.infrastructure.db import SessionFactory
|
||||
from app.infrastructure.milvus_knowledge_adapter import MilvusKnowledgeClient
|
||||
from app.service.knowledge_authority import KnowledgeMysqlAuthority
|
||||
from app.service.knowledge_config import KnowledgeRuntimeConfig
|
||||
from app.service.knowledge_retrieval_service import KnowledgeRetrievalService
|
||||
from app.service.model_gateway import DatabaseModelGateway
|
||||
|
||||
|
||||
class EmbeddingGateway(Protocol):
|
||||
async def embed(self, *, endpoint_code: str, text: str, timeout_ms: int) -> list[float]: ...
|
||||
|
||||
|
||||
class DatabaseEmbeddingAdapter:
|
||||
def __init__(
|
||||
self, endpoint_code: str, timeout_ms: int, *, gateway: EmbeddingGateway
|
||||
) -> None:
|
||||
self._endpoint_code = endpoint_code
|
||||
self._timeout_ms = timeout_ms
|
||||
self._gateway = gateway
|
||||
|
||||
async def embed(self, text: str) -> list[float]:
|
||||
return await self._gateway.embed(
|
||||
endpoint_code=self._endpoint_code, text=text, timeout_ms=self._timeout_ms
|
||||
)
|
||||
|
||||
|
||||
async def query_knowledge_tool(
|
||||
arguments: KnowledgeQuery, context: RequestContext
|
||||
) -> KnowledgeSearchResult:
|
||||
settings = get_settings()
|
||||
if not settings.knowledge_embedding_endpoint_code:
|
||||
return KnowledgeSearchResult(
|
||||
degraded=True, degradation_reason="embedding_endpoint_unconfigured"
|
||||
)
|
||||
# 知识向量端点与默认聊天端点隔离，避免回答模型被误用于检索。
|
||||
embedder = DatabaseEmbeddingAdapter(
|
||||
settings.knowledge_embedding_endpoint_code,
|
||||
settings.knowledge_embedding_timeout_ms,
|
||||
gateway=DatabaseModelGateway(),
|
||||
)
|
||||
# 兼容旧测试替身；真实 Settings 会优先提供本地/远程统一解析后的地址。
|
||||
milvus_uri = getattr(settings, "resolved_milvus_uri", settings.milvus_uri)
|
||||
vector_store = MilvusKnowledgeClient(milvus_uri, token=settings.milvus_token or None)
|
||||
# 权威元数据只读回查，确保对客答案始终来自已发布、有效的知识条目。
|
||||
async with SessionFactory() as session:
|
||||
authority = KnowledgeMysqlAuthority(session)
|
||||
service = KnowledgeRetrievalService(
|
||||
embedder, vector_store, KnowledgeRuntimeConfig(), authority
|
||||
)
|
||||
return await service.search(arguments, context)
|
||||
Reference in New Issue
Block a user