Update backend api

2026-02-08 15:52:16 +08:00
parent 727fe8a997
commit 7012f8edaf
15 changed files with 3436 additions and 19 deletions
--- a/api/docs/llm.md
+++ b/api/docs/llm.md
@@ -0,0 +1,401 @@
+# LLM 模型 (LLM Model) API
+
+LLM 模型 API 用于管理大语言模型的配置和调用。
+
+## 基础信息
+
+| 项目 | 值 |
+|------|-----|
+| Base URL | `/api/v1/llm` |
+| 认证方式 | Bearer Token (预留) |
+
+---
+
+## 数据模型
+
+### LLMModel
+
+```typescript
+interface LLMModel {
+  id: string;           // 模型唯一标识 (8位UUID)
+  user_id: number;      // 所属用户ID
+  name: string;         // 模型显示名称
+  vendor: string;       // 供应商: "OpenAI" | "SiliconFlow" | "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 模型列表
+
+```http
+GET /api/v1/llm
+```
+
+**Query Parameters:**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| model_type | string | 否 | - | 过滤类型: "text" \| "embedding" \| "rerank" |
+| enabled | boolean | 否 | - | 过滤启用状态 |
+| page | int | 否 | 1 | 页码 |
+| limit | int | 否 | 50 | 每页数量 |
+
+**Response:**
+
+```json
+{
+  "total": 5,
+  "page": 1,
+  "limit": 50,
+  "list": [
+    {
+      "id": "abc12345",
+      "user_id": 1,
+      "name": "GPT-4o",
+      "vendor": "OpenAI",
+      "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",
+      "type": "embedding",
+      "base_url": "https://api.openai.com/v1",
+      "api_key": "sk-***",
+      "model_name": "text-embedding-3-small",
+      "enabled": true
+    }
+  ]
+}
+```
+
+---
+
+### 2. 获取单个 LLM 模型详情
+
+```http
+GET /api/v1/llm/{id}
+```
+
+**Path Parameters:**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| id | string | 模型ID |
+
+**Response:**
+
+```json
+{
+  "id": "abc12345",
+  "user_id": 1,
+  "name": "GPT-4o",
+  "vendor": "OpenAI",
+  "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 模型
+
+```http
+POST /api/v1/llm
+```
+
+**Request Body:**
+
+```json
+{
+  "name": "GPT-4o",
+  "vendor": "OpenAI",
+  "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 模型
+
+```http
+PUT /api/v1/llm/{id}
+```
+
+**Request Body:** (部分更新)
+
+```json
+{
+  "name": "GPT-4o-Updated",
+  "temperature": 0.8,
+  "enabled": false
+}
+```
+
+---
+
+### 5. 删除 LLM 模型
+
+```http
+DELETE /api/v1/llm/{id}
+```
+
+**Response:**
+
+```json
+{
+  "message": "Deleted successfully"
+}
+```
+
+---
+
+### 6. 测试 LLM 模型连接
+
+```http
+POST /api/v1/llm/{id}/test
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "latency_ms": 150,
+  "message": "Connection successful"
+}
+```
+
+**错误响应:**
+
+```json
+{
+  "success": false,
+  "latency_ms": 200,
+  "message": "HTTP Error: 401 - Unauthorized"
+}
+```
+
+---
+
+### 7. 与 LLM 模型对话
+
+```http
+POST /api/v1/llm/{id}/chat
+```
+
+**Query Parameters:**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| message | string | 是 | - | 用户消息 |
+| system_prompt | string | 否 | - | 系统提示词 |
+| max_tokens | int | 否 | 1000 | 最大生成token数 |
+| temperature | number | 否 | 模型配置 | 温度参数 |
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "reply": "您好！有什么可以帮助您的？",
+  "usage": {
+    "prompt_tokens": 20,
+    "completion_tokens": 15,
+    "total_tokens": 35
+  }
+}
+```
+
+---
+
+## Schema 定义
+
+```python
+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
+
+```json
+{
+  "vendor": "OpenAI",
+  "base_url": "https://api.openai.com/v1",
+  "api_key": "sk-xxx",
+  "model_name": "gpt-4o",
+  "type": "text",
+  "temperature": 0.7
+}
+```
+
+### SiliconFlow
+
+```json
+{
+  "vendor": "SiliconFlow",
+  "base_url": "https://api.siliconflow.com/v1",
+  "api_key": "sf-xxx",
+  "model_name": "deepseek-v3",
+  "type": "text",
+  "temperature": 0.7
+}
+```
+
+### Dify
+
+```json
+{
+  "vendor": "Dify",
+  "base_url": "https://your-dify.domain.com/v1",
+  "api_key": "app-xxx",
+  "model_name": "gpt-4",
+  "type": "text"
+}
+```
+
+### Embedding 模型
+
+```json
+{
+  "vendor": "OpenAI",
+  "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 模型测试 |
+
+### 运行测试
+
+```bash
+# 运行 LLM 相关测试
+pytest api/tests/test_llm.py -v
+
+# 运行所有测试
+pytest api/tests/ -v
+```