# 模型接入 (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" | "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;       // "OpenAI Compatible" | "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"
    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"
}
```

### OpenAI Compatible

```json
{
  "vendor": "OpenAI Compatible",
  "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"
}
```