Initial commit

embedding/models.py

@@ -0,0 +1,49 @@
+"""Embedding 模块的数据模型 (M5)。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class EmbeddingProviderType(StrEnum):
+    """支持的 embedding provider 标识。"""
+
+    DASHSCOPE = "dashscope"   # 远程 Qwen / 百炼
+    LOCAL_BGE = "local-bge"   # 本地 BGE-M3
+
+
+class EmbeddingResult(BaseModel):
+    """单篇文章的嵌入结果(落盘格式)。"""
+
+    url_hash: str = Field(..., description="主键,与 Article.url_hash 一致")
+    source_id: str = Field(..., description="来源源 id")
+    title: str = Field(..., description="原文标题(便于人工检索)")
+    text: str = Field(
+        ..., description="实际送入 embedder 的文本(已截断/拼接)"
+    )
+    vector: list[float] = Field(..., description="嵌入向量")
+    dim: int = Field(..., gt=0, description="向量维度")
+
+    provider: str = Field(..., description="dashscope / local-bge")
+    model: str = Field(..., description="嵌入模型名")
+    embedded_at: datetime = Field(default_factory=datetime.now)
+    char_count: int = Field(default=0, ge=0, description="text 字符数,便于排查")
+    publish_time: datetime | None = None
+
+    def short_summary(self) -> str:
+        return (
+            f"[{self.source_id}] {self.title[:30]} "
+            f"dim={self.dim} provider={self.provider}"
+        )
+
+
+class EmbeddingError(Exception):
+    """嵌入调用失败。"""
+
+    def __init__(self, reason: str, *, attempts: int = 0) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.attempts = attempts