初始化提交

yuanqi/src/models/schemas.py

@@ -0,0 +1,131 @@
+"""
+请求 / 响应 Pydantic 模型定义。
+
+Chat 透传 OpenAI 兼容格式，Embeddings 需组装响应，Reranker 使用自定义格式。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# ── ASR（语音识别）─────────────────────────────────────────────────────────
+
+
+class ASRRequest(BaseModel):
+    model: str = Field(default="SenseVoiceSmall", description="ASR 模型名称")
+    language: str | None = Field(
+        default=None,
+        description="语言提示（ISO-639-1：zh/en/ja/ko/yue 等），auto 表示自动检测",
+    )
+
+
+class ASRResponse(BaseModel):
+    text: str = Field(description="转写文本")
+    model: str = Field(description="使用的模型名称")
+    language: str | None = Field(default=None, description="检测到的语言")
+
+
+class ASRTranscriptionResponse(BaseModel):
+    """OpenAI Whisper 兼容的转写响应。"""
+
+    text: str = Field(description="转写文本")
+
+
+# ── Embedding ──────────────────────────────────────────────────────────
+
+
+class EmbeddingRequest(BaseModel):
+    model: str = Field(description="模型名称")
+    input: str | list[str] = Field(description="输入文本，单条字符串或字符串列表")
+    output_types: list[str] = Field(
+        default_factory=lambda: ["dense"],
+        description="输出表示类型，默认为 ['dense']。支持值：\n"
+        "- ``dense`` — 稠密向量（OpenAI 兼容）\n"
+        "- ``sparse`` — 稀疏向量（BGE-M3 lexical weights）\n"
+        "- ``colbert`` — 多向量表示（BGE-M3 ColBERT）\n"
+        "扩展语法（框架预留，引擎就绪后生效）：\n"
+        "- ``dense:N`` — Matryoshka 截断维度（如 ``dense:384``）\n"
+        "- ``dense:image`` — 图像模态向量\n"
+        "- ``dense:audio`` — 音频模态向量\n"
+        "- ``hidden_state:layerN`` — 指定层 Transformer 输出",
+    )
+
+
+class EmbeddingResponse(BaseModel):
+    object: str = "list"
+    model: str = Field(description="使用的模型名称")
+    data: list[dict[str, Any]] = Field(
+        description="嵌入结果列表，每项必含 object/index/embedding（稠密向量），"
+        "请求稀疏/ColBERT 时额外含 sparse_embedding / colbert_embedding"
+    )
+    usage: dict = Field(
+        default_factory=lambda: {"prompt_tokens": 0, "total_tokens": 0},
+        description="Token 用量与输出表示元数据。\n"
+        "OpenAI 兼容：prompt_tokens / total_tokens\n"
+        "扩展 details.input：count / tokens / total_tokens\n"
+        "扩展 details.representations[]：每项含 type / modality 及类型专属元数据",
+    )
+
+
+# ── Reranker ────────────────────────────────────────────────────────────
+
+
+class RerankRequest(BaseModel):
+    model: str = Field(description="重排序模型名称")
+    query: str = Field(description="搜索查询文本")
+    documents: list[str] = Field(description="待排序文档列表", min_length=1)
+    top_n: int | None = Field(None, description="返回前 N 个最相关结果，默认返回全部排序")
+
+
+class RerankResult(BaseModel):
+    index: int = Field(description="在原始 documents 中的位置")
+    document: str = Field(description="文档内容")
+    relevance_score: float = Field(description="相关性分数（0~1，越高越相关）")
+
+
+class RerankResponse(BaseModel):
+    model: str = Field(description="使用的模型名称")
+    results: list[RerankResult] = Field(description="排序结果（按相关性降序）")
+    usage: dict = Field(
+        default_factory=lambda: {
+            "input": {"query_tokens": 0, "document_tokens": [], "total_tokens": 0},
+            "compute": {"pairs": 0, "tokens": 0},
+        },
+        description="Token 用量：input 为用户输入（document_tokens 按文档逐条），"
+        "compute 为实际推理开销",
+    )
+
+
+# ── 健康检查 ────────────────────────────────────────────────────────────
+
+
+class EngineStatus(BaseModel):
+    status: str = Field(description="引擎状态：ok / error / unavailable")
+
+
+class ModelStatus(BaseModel):
+    name: str = Field(description="模型名称")
+    type: str = Field(description="模型类型：llm / embedding / vision / reranker")
+    status: str = Field(description="状态：loaded / loading / error")
+
+
+class HealthResponse(BaseModel):
+    status: str = Field(description="服务整体状态：ok / degraded / error")
+    engines: dict[str, EngineStatus] = Field(description="各引擎状态")
+    loaded_models: list[ModelStatus] = Field(default_factory=list, description="已加载模型列表")
+    version: str = Field(default=__import__("src").__version__, description="元炁版本")
+
+
+# ── 错误响应 ────────────────────────────────────────────────────────────
+
+
+class ErrorDetail(BaseModel):
+    code: str = Field(description="错误码")
+    message: str = Field(description="错误描述")
+    detail: Any | None = Field(None, description="额外详情")
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetail