AI-VideoAssistant/api/docs/model-access.md

模型接入 (Model Access) API

模型接入 API 用于管理 LLM、Embedding、Rerank 等 AI 模型的配置。

基础信息

项目	值
Base URL	/api/v1/models
认证方式	Bearer Token (预留)

---

数据模型

LLMModel

interface LLMModel {
  id: string;           // 模型唯一标识
  user_id: number;      // 所属用户ID
  name: string;         // 模型显示名称
  vendor: string;       // 供应商: "OpenAI Compatible" | "SiliconFlow" | "Dify" | "FastGPT"
  type: string;         // 类型: "text" | "embedding" | "rerank"
  base_url: string;     // API Base URL
  api_key: string;       // API Key
  model_name?: string;   // 实际模型名称
  temperature?: number;  // 温度参数 (仅text类型)
  context_length?: int; // 上下文长度
  enabled: boolean;     // 是否启用
  created_at: string;
  updated_at: string;
}

ASRModel (语音识别模型)

interface ASRModel {
  id: string;
  user_id: number;
  name: string;
  vendor: string;       // "OpenAI Compatible" | "Azure" | "阿里云" | "讯飞"
  language: string;      // "zh" | "en" | "Multi-lingual"
  base_url: string;
  api_key: string;
  model_name?: string;  // 如 "whisper-1", "SenseVoiceSmall"
  enabled: boolean;
  created_at: string;
}

TTSModel (语音合成模型 - 可选)

interface TTSModel {
  id: string;
  user_id: number;
  name: string;
  vendor: string;       // "Ali" | "Volcano" | "Minimax" | "硅基流动"
  language: string;      // "zh" | "en"
  voice_list?: string[]; // 支持的声音列表
  enabled: boolean;
  created_at: string;
}

---

API 端点

LLM 模型

1. 获取 LLM 模型列表

GET /api/v1/models/llm

Query Parameters:

参数	类型	必填	说明
type	string	否	过滤类型: "text" | "embedding" | "rerank"
vendor	string	否	过滤供应商
enabled	boolean	否	过滤启用状态

Response:

{
  "total": 5,
  "list": [
    {
      "id": "llm_001",
      "user_id": 1,
      "name": "GPT-4o",
      "vendor": "OpenAI Compatible",
      "type": "text",
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-***",
      "model_name": "gpt-4o",
      "temperature": 0.7,
      "context_length": 128000,
      "enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "emb_001",
      "user_id": 1,
      "name": "Embedding-3-Small",
      "vendor": "OpenAI Compatible",
      "type": "embedding",
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-***",
      "model_name": "text-embedding-3-small",
      "enabled": true
    }
  ]
}

2. 获取单个 LLM 模型详情

GET /api/v1/models/llm/{id}

3. 创建 LLM 模型

POST /api/v1/models/llm

Request Body:

{
  "name": "GPT-4o",
  "vendor": "OpenAI Compatible",
  "type": "text",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-your-api-key",
  "model_name": "gpt-4o",
  "temperature": 0.7,
  "context_length": 128000,
  "enabled": true
}

4. 更新 LLM 模型

PUT /api/v1/models/llm/{id}

Request Body: (部分更新)

{
  "name": "GPT-4o-Updated",
  "temperature": 0.8,
  "enabled": false
}

5. 删除 LLM 模型

DELETE /api/v1/models/llm/{id}

6. 测试 LLM 模型连接

POST /api/v1/models/llm/{id}/test

Response:

{
  "success": true,
  "latency_ms": 150,
  "message": "Connection successful"
}

---

ASR 模型

1. 获取 ASR 模型列表

GET /api/v1/models/asr

Response:

{
  "total": 3,
  "list": [
    {
      "id": "asr_001",
      "user_id": 1,
      "name": "Whisper-1",
      "vendor": "OpenAI Compatible",
      "language": "Multi-lingual",
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-***",
      "model_name": "whisper-1",
      "enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "asr_002",
      "user_id": 1,
      "name": "SenseVoice-Small",
      "vendor": "OpenAI Compatible",
      "language": "zh",
      "base_url": "https://api.speech.ai/v1",
      "api_key": "sk-***",
      "model_name": "sensevoice-small",
      "enabled": true
    }
  ]
}

2. 创建 ASR 模型

POST /api/v1/models/asr

Request Body:

{
  "name": "SenseVoice-Small",
  "vendor": "OpenAI Compatible",
  "language": "zh",
  "base_url": "https://api.speech.ai/v1",
  "api_key": "sk-your-api-key",
  "model_name": "sensevoice-small",
  "enabled": true
}

3. 测试 ASR 模型

POST /api/v1/models/asr/{id}/test

Request Body:

{
  "audio_url": "https://example.com/test.wav"
}

Response:

{
  "success": true,
  "transcript": "测试音频内容",
  "language": "zh",
  "latency_ms": 500
}

---

TTS 模型 (可选)

1. 获取 TTS 模型列表

GET /api/v1/models/tts

2. 创建 TTS 模型

POST /api/v1/models/tts

Request Body:

{
  "name": "阿里云语音合成",
  "vendor": "Ali",
  "language": "zh",
  "base_url": "https://nlp.cn-shanghai.aliyuncs.com",
  "api_key": "sk-***",
  "enabled": true
}

---

推荐的 Schema 定义

# ============ LLM Model ============
class LLMModelType(str, Enum):
    TEXT = "text"
    EMBEDDING = "embedding"
    RERANK = "rerank"

class LLMModelVendor(str, Enum):
    OPENAI_COMPATIBLE = "OpenAI Compatible"
    SILICONFLOW = "SiliconFlow"
    DIFY = "Dify"
    FASTGPT = "FastGPT"

class LLMModelBase(BaseModel):
    name: str
    vendor: str
    type: LLMModelType
    base_url: str
    api_key: str
    model_name: Optional[str] = None
    temperature: Optional[float] = None
    context_length: Optional[int] = None
    enabled: bool = True

class LLMModelCreate(LLMModelBase):
    pass

class LLMModelUpdate(BaseModel):
    name: Optional[str] = None
    base_url: Optional[str] = None
    api_key: Optional[str] = None
    model_name: Optional[str] = None
    temperature: Optional[float] = None
    context_length: Optional[int] = None
    enabled: Optional[bool] = None

class LLMModelOut(LLMModelBase):
    id: str
    user_id: int
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

# ============ ASR Model ============
class ASRModelBase(BaseModel):
    name: str
    vendor: str
    language: str  # "zh" | "en" | "Multi-lingual"
    base_url: str
    api_key: str
    model_name: Optional[str] = None
    enabled: bool = True

class ASRModelCreate(ASRModelBase):
    pass

class ASRModelOut(ASRModelBase):
    id: str
    user_id: int
    created_at: datetime

    class Config:
        from_attributes = True

---

供应商配置示例

OpenAI Compatible

{
  "vendor": "OpenAI Compatible",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxx",
  "model_name": "gpt-4o"
}

SiliconFlow

{
  "vendor": "SiliconFlow",
  "base_url": "https://api.siliconflow.com/v1",
  "api_key": "sf-xxx",
  "model_name": "deepseek-v3"
}

Dify

{
  "vendor": "Dify",
  "base_url": "https://your-dify.domain.com/v1",
  "api_key": "app-xxx",
  "model_name": "gpt-4"
}