Add docs for api backend
This commit is contained in:
Xin Wang
412
api/docs/model-access.md
Normal file
412
api/docs/model-access.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# 模型接入 (Model Access) API
|
||||
|
||||
模型接入 API 用于管理 LLM、Embedding、Rerank 等 AI 模型的配置。
|
||||
|
||||
## 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| Base URL | `/api/v1/models` |
|
||||
| 认证方式 | Bearer Token (预留) |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### LLMModel
|
||||
|
||||
```typescript
|
||||
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 (语音识别模型)
|
||||
|
||||
```typescript
|
||||
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 (语音合成模型 - 可选)
|
||||
|
||||
```typescript
|
||||
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 模型列表
|
||||
|
||||
```http
|
||||
GET /api/v1/models/llm
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| type | string | 否 | 过滤类型: "text" \| "embedding" \| "rerank" |
|
||||
| vendor | string | 否 | 过滤供应商 |
|
||||
| enabled | boolean | 否 | 过滤启用状态 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 模型详情
|
||||
|
||||
```http
|
||||
GET /api/v1/models/llm/{id}
|
||||
```
|
||||
|
||||
#### 3. 创建 LLM 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/models/llm
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 模型
|
||||
|
||||
```http
|
||||
PUT /api/v1/models/llm/{id}
|
||||
```
|
||||
|
||||
**Request Body:** (部分更新)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "GPT-4o-Updated",
|
||||
"temperature": 0.8,
|
||||
"enabled": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 删除 LLM 模型
|
||||
|
||||
```http
|
||||
DELETE /api/v1/models/llm/{id}
|
||||
```
|
||||
|
||||
#### 6. 测试 LLM 模型连接
|
||||
|
||||
```http
|
||||
POST /api/v1/models/llm/{id}/test
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"latency_ms": 150,
|
||||
"message": "Connection successful"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ASR 模型
|
||||
|
||||
#### 1. 获取 ASR 模型列表
|
||||
|
||||
```http
|
||||
GET /api/v1/models/asr
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/models/asr
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/models/asr/{id}/test
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"audio_url": "https://example.com/test.wav"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"transcript": "测试音频内容",
|
||||
"language": "zh",
|
||||
"latency_ms": 500
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### TTS 模型 (可选)
|
||||
|
||||
#### 1. 获取 TTS 模型列表
|
||||
|
||||
```http
|
||||
GET /api/v1/models/tts
|
||||
```
|
||||
|
||||
#### 2. 创建 TTS 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/models/tts
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "阿里云语音合成",
|
||||
"vendor": "Ali",
|
||||
"language": "zh",
|
||||
"base_url": "https://nlp.cn-shanghai.aliyuncs.com",
|
||||
"api_key": "sk-***",
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 推荐的 Schema 定义
|
||||
|
||||
```python
|
||||
# ============ 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
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "OpenAI Compatible",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-xxx",
|
||||
"model_name": "gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
### SiliconFlow
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "SiliconFlow",
|
||||
"base_url": "https://api.siliconflow.com/v1",
|
||||
"api_key": "sf-xxx",
|
||||
"model_name": "deepseek-v3"
|
||||
}
|
||||
```
|
||||
|
||||
### Dify
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "Dify",
|
||||
"base_url": "https://your-dify.domain.com/v1",
|
||||
"api_key": "app-xxx",
|
||||
"model_name": "gpt-4"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user