wx44wx/AI-VideoAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
AI-VideoAssistant/api/docs/llm.md

9.0 KiB
Raw Permalink Blame History

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
  }
}

8. 预览模型输出

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

预览模型输出，支持 text(chat) 与 embedding 两类模型。

Request Body:

{
  "message": "请介绍一下你自己",
  "system_prompt": "你是一个专业的AI助手",
  "max_tokens": 512,
  "temperature": 0.7
}

Response (text model):

{
  "success": true,
  "reply": "您好！我是一个...",
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  },
  "latency_ms": 1500,
  "error": null
}

Response (embedding model):

{
  "success": true,
  "reply": "Embedding generated successfully. dims=1536. head=[0.012345, -0.023456, ...]",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  },
  "latency_ms": 800,
  "error": null
}

Fields 说明:

字段 类型 必填 说明
message string 是 用户消息/嵌入文本
system_prompt string 否 系统提示词 (仅 text 模型)
max_tokens int 否 最大生成 token 数 (默认 512)
temperature float 否 温度参数
api_key string 否 覆盖模型配置的 API Key

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
Reference in New Issue View Git Blame Copy Permalink