AI-VideoAssistant/api/docs/llm.md

LLM 模型 (LLM Model) API

LLM 模型 API 用于管理大语言模型的配置和调用。

基础信息

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

---

数据模型

LLMModel

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

---

API 端点

1. 获取 LLM 模型列表

GET /api/v1/llm

Query Parameters:

参数	类型	必填	默认值	说明
model_type	string	否	-	过滤类型: "text" | "embedding" | "rerank"
enabled	boolean	否	-	过滤启用状态
page	int	否	1	页码
limit	int	否	50	每页数量

Response:

{
  "total": 5,
  "page": 1,
  "limit": 50,
  "list": [
    {
      "id": "abc12345",
      "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",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "def67890",
      "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/llm/{id}

Path Parameters:

参数	类型	说明
id	string	模型ID

Response:

{
  "id": "abc12345",
  "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",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

3. 创建 LLM 模型

POST /api/v1/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
}

Fields 说明:

字段	类型	必填	说明
name	string	是	模型显示名称
vendor	string	是	供应商名称
type	string	是	模型类型: "text" / "embedding" / "rerank"
base_url	string	是	API Base URL
api_key	string	是	API Key
model_name	string	否	实际模型名称
temperature	number	否	温度参数，默认 0.7
context_length	int	否	上下文长度
enabled	boolean	否	是否启用，默认 true
id	string	否	指定模型ID，默认自动生成

---

4. 更新 LLM 模型

PUT /api/v1/llm/{id}

Request Body: (部分更新)

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

---

5. 删除 LLM 模型

DELETE /api/v1/llm/{id}

Response:

{
  "message": "Deleted successfully"
}

---

6. 测试 LLM 模型连接

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

Response:

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

错误响应:

{
  "success": false,
  "latency_ms": 200,
  "message": "HTTP Error: 401 - Unauthorized"
}

---

7. 与 LLM 模型对话

POST /api/v1/llm/{id}/chat

Query Parameters:

参数	类型	必填	默认值	说明
message	string	是	-	用户消息
system_prompt	string	否	-	系统提示词
max_tokens	int	否	1000	最大生成token数
temperature	number	否	模型配置	温度参数

Response:

{
  "success": true,
  "reply": "您好！有什么可以帮助您的？",
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 15,
    "total_tokens": 35
  }
}

---

Schema 定义

from enum import Enum
from pydantic import BaseModel
from typing import Optional
from datetime import datetime

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

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):
    id: Optional[str] = None

class LLMModelUpdate(BaseModel):
    name: Optional[str] = None
    vendor: 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

class LLMModelTestResponse(BaseModel):
    success: bool
    latency_ms: int
    message: str

---

供应商配置示例

OpenAI Compatible (OpenAI Endpoint)

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

OpenAI Compatible

{
  "vendor": "OpenAI Compatible",
  "base_url": "https://api.siliconflow.com/v1",
  "api_key": "sf-xxx",
  "model_name": "deepseek-v3",
  "type": "text",
  "temperature": 0.7
}

Dify

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

Embedding 模型

{
  "vendor": "OpenAI Compatible",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxx",
  "model_name": "text-embedding-3-small",
  "type": "embedding"
}

---

单元测试

项目包含完整的单元测试，位于 api/tests/test_llm.py。

测试用例概览

测试方法	说明
test_get_llm_models_empty	空数据库获取测试
test_create_llm_model	创建模型测试
test_create_llm_model_minimal	最小数据创建测试
test_get_llm_model_by_id	获取单个模型测试
test_get_llm_model_not_found	获取不存在模型测试
test_update_llm_model	更新模型测试
test_delete_llm_model	删除模型测试
test_list_llm_models_with_pagination	分页测试
test_filter_llm_models_by_type	按类型过滤测试
test_filter_llm_models_by_enabled	按启用状态过滤测试
test_create_llm_model_with_all_fields	全字段创建测试
test_test_llm_model_success	测试连接成功测试
test_test_llm_model_failure	测试连接失败测试
test_different_llm_vendors	多供应商测试
test_embedding_llm_model	Embedding 模型测试

运行测试

# 运行 LLM 相关测试
pytest api/tests/test_llm.py -v

# 运行所有测试
pytest api/tests/ -v