623 lines
No EOL
15 KiB
Text
623 lines
No EOL
15 KiB
Text
# LLM API 转发平台 API 开发文档
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [简介](#1-简介)
|
||
2. [认证与授权](#2-认证与授权)
|
||
- [2.1 认证令牌（Auth Token）](#21-认证令牌auth-token)
|
||
- [2.2 访问令牌（Access Token）](#22-访问令牌access-token)
|
||
3. [API 概览](#3-api-概览)
|
||
- [3.1 客户用户 API](#31-客户用户-api)
|
||
- [3.2 管理员 API](#32-管理员-api)
|
||
4. [API 详细说明](#4-api-详细说明)
|
||
- [4.1 认证 API](#41-认证-api)
|
||
- [4.1.1 获取访问令牌](#411-获取访问令牌)
|
||
- [4.2 客户用户 API](#42-客户用户-api)
|
||
- [4.2.1 发送提示词请求](#421-发送提示词请求)
|
||
- [4.3 管理员 API](#43-管理员-api)
|
||
- [4.3.1 LLM 提供商管理](#431-llm-提供商管理)
|
||
- [4.3.1.1 新增 LLM 提供商](#4311-新增-llm-提供商)
|
||
- [4.3.1.2 修改 LLM 提供商](#4312-修改-llm-提供商)
|
||
- [4.3.1.3 删除 LLM 提供商](#4313-删除-llm-提供商)
|
||
- [4.3.1.4 获取 LLM 提供商列表](#4314-获取-llm-提供商列表)
|
||
- [4.3.2 客户用户管理](#432-客户用户管理)
|
||
- [4.3.2.1 新增客户用户](#4321-新增客户用户)
|
||
- [4.3.2.2 修改客户用户](#4322-修改客户用户)
|
||
- [4.3.2.3 删除客户用户](#4323-删除客户用户)
|
||
- [4.3.2.4 获取客户用户列表](#4324-获取客户用户列表)
|
||
- [4.3.3 生成认证令牌](#433-生成认证令牌)
|
||
5. [请求与响应格式](#5-请求与响应格式)
|
||
- [5.1 通用请求头](#51-通用请求头)
|
||
- [5.2 响应格式](#52-响应格式)
|
||
6. [错误代码](#6-错误代码)
|
||
7. [安全性考虑](#7-安全性考虑)
|
||
8. [示例](#8-示例)
|
||
- [8.1 获取访问令牌示例](#81-获取访问令牌示例)
|
||
- [8.2 发送提示词请求示例](#82-发送提示词请求示例)
|
||
9. [结论](#9-结论)
|
||
|
||
---
|
||
|
||
## 1. 简介
|
||
|
||
本文档详细描述了 LLM API 转发平台的 API 接口规范，旨在指导开发者基于 Laravel、MySQL 和 Redis 技术栈，实现平台的 API 功能。平台提供了基于令牌的 LLM 调用服务，支持多层级管理员管理和 LLM 提供商的动态配置。
|
||
|
||
---
|
||
|
||
## 2. 认证与授权
|
||
|
||
平台采用基于令牌的认证机制，包括长期有效的**认证令牌（Auth Token）**和短期有效的**访问令牌（Access Token）**。
|
||
|
||
### 2.1 认证令牌（Auth Token）
|
||
|
||
- **用途**：客户用户使用认证令牌获取访问令牌。
|
||
- **特点**：
|
||
- 由管理员生成并分发给客户用户。
|
||
- 长期有效，或由管理员设定过期时间。
|
||
|
||
### 2.2 访问令牌（Access Token）
|
||
|
||
- **用途**：客户用户使用访问令牌访问受保护的 API 接口。
|
||
- **特点**：
|
||
- 由客户用户使用认证令牌获取。
|
||
- 短期有效（如 1 小时），存储在 Redis 中，支持自动过期和动态注销。
|
||
|
||
---
|
||
|
||
## 3. API 概览
|
||
|
||
### 3.1 客户用户 API
|
||
|
||
- **获取访问令牌**
|
||
- `POST /api/auth/token`
|
||
- **发送提示词请求**
|
||
- `POST /api/llm/request`
|
||
|
||
### 3.2 管理员 API
|
||
|
||
- **LLM 提供商管理**
|
||
- 新增 LLM 提供商：`POST /api/admin/llm-providers`
|
||
- 修改 LLM 提供商：`PUT /api/admin/llm-providers/{id}`
|
||
- 删除 LLM 提供商：`DELETE /api/admin/llm-providers/{id}`
|
||
- 获取 LLM 提供商列表：`GET /api/admin/llm-providers`
|
||
- **客户用户管理**
|
||
- 新增客户用户：`POST /api/admin/clients`
|
||
- 修改客户用户：`PUT /api/admin/clients/{id}`
|
||
- 删除客户用户：`DELETE /api/admin/clients/{id}`
|
||
- 获取客户用户列表：`GET /api/admin/clients`
|
||
- **生成认证令牌**
|
||
- `POST /api/admin/clients/{id}/auth-token`
|
||
|
||
---
|
||
|
||
## 4. API 详细说明
|
||
|
||
### 4.1 认证 API
|
||
|
||
#### 4.1.1 获取访问令牌
|
||
|
||
- **URL**：`/api/auth/token`
|
||
- **方法**：`POST`
|
||
- **描述**：使用认证令牌获取短期访问令牌。
|
||
|
||
**请求参数**：
|
||
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"auth_token": "string"
|
||
}
|
||
```
|
||
- `auth_token`（必填）：管理员分发的认证令牌。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"access_token": "string",
|
||
"expires_in": 3600
|
||
}
|
||
```
|
||
- `access_token`：短期访问令牌。
|
||
- `expires_in`：令牌有效期，单位为秒。
|
||
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "invalid_auth_token",
|
||
"message": "认证令牌无效。"
|
||
}
|
||
```
|
||
|
||
### 4.2 客户用户 API
|
||
|
||
#### 4.2.1 发送提示词请求
|
||
|
||
- **URL**：`/api/llm/request`
|
||
- **方法**：`POST`
|
||
- **描述**：使用访问令牌向绑定的 LLM 提供商发送提示词请求。
|
||
|
||
**请求参数**：
|
||
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- `Authorization: Bearer {access_token}`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"prompt": "string"
|
||
}
|
||
```
|
||
- `prompt`（必填）：提示词内容。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"response": "LLM 提供商返回的响应内容"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "invalid_access_token",
|
||
"message": "访问令牌无效或已过期。"
|
||
}
|
||
```
|
||
|
||
### 4.3 管理员 API
|
||
|
||
> **注意**：管理员 API 需要使用管理员的身份认证（如 JWT Token 或 Session），具体认证方式可根据系统需求设计。
|
||
|
||
#### 4.3.1 LLM 提供商管理
|
||
|
||
##### 4.3.1.1 新增 LLM 提供商
|
||
|
||
- **URL**：`/api/admin/llm-providers`
|
||
- **方法**：`POST`
|
||
- **描述**：新增一个 LLM 提供商。
|
||
|
||
**请求参数**：
|
||
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"service_name": "string",
|
||
"api_url": "string",
|
||
"api_token": "string"
|
||
}
|
||
```
|
||
- `name`（必填）：提供商名称。
|
||
- `service_name`（必填）：对应的服务逻辑名称。
|
||
- `api_url`（必填）：提供商的 API 接口地址。
|
||
- `api_token`（必填）：调用提供商 API 所需的令牌。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "OpenAI",
|
||
"service_name": "OpenAIService",
|
||
"api_url": "https://api.openai.com/v1/engines/davinci/completions",
|
||
"api_token": "sk-xxxxx",
|
||
"created_at": "2023-10-01T12:00:00Z"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "validation_error",
|
||
"message": "提供商名称已存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.1.2 修改 LLM 提供商
|
||
|
||
- **URL**：`/api/admin/llm-providers/{id}`
|
||
- **方法**：`PUT`
|
||
- **描述**：修改指定的 LLM 提供商信息。
|
||
|
||
**请求参数**：
|
||
|
||
- **路径参数**：
|
||
- `id`（必填）：LLM 提供商的 ID。
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"service_name": "string",
|
||
"api_url": "string",
|
||
"api_token": "string"
|
||
}
|
||
```
|
||
- 参数同新增接口，可选填。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "OpenAI",
|
||
"service_name": "OpenAIService",
|
||
"api_url": "https://api.openai.com/v1/engines/davinci/completions",
|
||
"api_token": "sk-xxxxx",
|
||
"updated_at": "2023-10-02T12:00:00Z"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "not_found",
|
||
"message": "LLM 提供商不存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.1.3 删除 LLM 提供商
|
||
|
||
- **URL**：`/api/admin/llm-providers/{id}`
|
||
- **方法**：`DELETE`
|
||
- **描述**：删除指定的 LLM 提供商。
|
||
|
||
**请求参数**：
|
||
|
||
- **路径参数**：
|
||
- `id`（必填）：LLM 提供商的 ID。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"message": "LLM 提供商已删除。"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "not_found",
|
||
"message": "LLM 提供商不存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.1.4 获取 LLM 提供商列表
|
||
|
||
- **URL**：`/api/admin/llm-providers`
|
||
- **方法**：`GET`
|
||
- **描述**：获取所有 LLM 提供商的列表。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "OpenAI",
|
||
"service_name": "OpenAIService",
|
||
"api_url": "https://api.openai.com/v1/engines/davinci/completions",
|
||
"created_at": "2023-10-01T12:00:00Z"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "Anthropic",
|
||
"service_name": "AnthropicService",
|
||
"api_url": "https://api.anthropic.com/v1/complete",
|
||
"created_at": "2023-10-01T13:00:00Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 4.3.2 客户用户管理
|
||
|
||
##### 4.3.2.1 新增客户用户
|
||
|
||
- **URL**：`/api/admin/clients`
|
||
- **方法**：`POST`
|
||
- **描述**：新增一个客户用户，并绑定 LLM 提供商。
|
||
|
||
**请求参数**：
|
||
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"llm_provider_id": 1
|
||
}
|
||
```
|
||
- `name`（必填）：客户用户名称。
|
||
- `llm_provider_id`（必填）：绑定的 LLM 提供商 ID。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"id": 1001,
|
||
"name": "Client A",
|
||
"llm_provider_id": 1,
|
||
"created_at": "2023-10-01T14:00:00Z"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "validation_error",
|
||
"message": "客户用户名称已存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.2.2 修改客户用户
|
||
|
||
- **URL**：`/api/admin/clients/{id}`
|
||
- **方法**：`PUT`
|
||
- **描述**：修改指定的客户用户信息。
|
||
|
||
**请求参数**：
|
||
|
||
- **路径参数**：
|
||
- `id`（必填）：客户用户的 ID。
|
||
- **Header**：
|
||
- `Content-Type: application/json`
|
||
- **Body**：
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"llm_provider_id": 2
|
||
}
|
||
```
|
||
- 参数可选填。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"id": 1001,
|
||
"name": "Client A Updated",
|
||
"llm_provider_id": 2,
|
||
"updated_at": "2023-10-02T14:00:00Z"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "not_found",
|
||
"message": "客户用户不存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.2.3 删除客户用户
|
||
|
||
- **URL**：`/api/admin/clients/{id}`
|
||
- **方法**：`DELETE`
|
||
- **描述**：删除指定的客户用户。
|
||
|
||
**请求参数**：
|
||
|
||
- **路径参数**：
|
||
- `id`（必填）：客户用户的 ID。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"message": "客户用户已删除。"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "not_found",
|
||
"message": "客户用户不存在。"
|
||
}
|
||
```
|
||
|
||
##### 4.3.2.4 获取客户用户列表
|
||
|
||
- **URL**：`/api/admin/clients`
|
||
- **方法**：`GET`
|
||
- **描述**：获取所有客户用户的列表。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
[
|
||
{
|
||
"id": 1001,
|
||
"name": "Client A",
|
||
"llm_provider_id": 1,
|
||
"created_at": "2023-10-01T14:00:00Z"
|
||
},
|
||
{
|
||
"id": 1002,
|
||
"name": "Client B",
|
||
"llm_provider_id": 2,
|
||
"created_at": "2023-10-01T15:00:00Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 4.3.3 生成认证令牌
|
||
|
||
- **URL**：`/api/admin/clients/{id}/auth-token`
|
||
- **方法**：`POST`
|
||
- **描述**：为指定的客户用户生成一个新的认证令牌。
|
||
|
||
**请求参数**：
|
||
|
||
- **路径参数**：
|
||
- `id`（必填）：客户用户的 ID。
|
||
|
||
**响应示例**：
|
||
|
||
- **成功**：
|
||
```json
|
||
{
|
||
"client_id": 1001,
|
||
"auth_token": "abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012",
|
||
"created_at": "2023-10-01T16:00:00Z"
|
||
}
|
||
```
|
||
- **失败**：
|
||
```json
|
||
{
|
||
"error": "not_found",
|
||
"message": "客户用户不存在。"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 请求与响应格式
|
||
|
||
### 5.1 通用请求头
|
||
|
||
- `Content-Type: application/json`
|
||
- 对于需要认证的接口，使用以下方式传递令牌：
|
||
- **客户用户访问令牌**：`Authorization: Bearer {access_token}`
|
||
- **管理员认证**：根据系统设计，可采用 `Authorization: Bearer {admin_token}`，或使用 Session/Cookie。
|
||
|
||
### 5.2 响应格式
|
||
|
||
- 所有响应均为 JSON 格式。
|
||
- 成功响应：
|
||
- HTTP 状态码为 `200` 或 `201`，响应体为请求的数据。
|
||
- 失败响应：
|
||
- HTTP 状态码为 `4xx` 或 `5xx`，响应体包含 `error` 和 `message` 字段。
|
||
|
||
**错误响应示例**：
|
||
|
||
```json
|
||
{
|
||
"error": "invalid_request",
|
||
"message": "请求参数缺失。"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 错误代码
|
||
|
||
| 错误代码 | HTTP 状态码 | 描述 |
|
||
|------------------------|-------------|------------------------------|
|
||
| `invalid_request` | 400 | 请求无效，参数缺失或格式错误。 |
|
||
| `unauthorized` | 401 | 未授权，令牌无效或未提供。 |
|
||
| `forbidden` | 403 | 禁止访问，没有权限。 |
|
||
| `not_found` | 404 | 资源不存在。 |
|
||
| `validation_error` | 422 | 请求参数验证失败。 |
|
||
| `server_error` | 500 | 服务器内部错误。 |
|
||
|
||
---
|
||
|
||
## 7. 安全性考虑
|
||
|
||
- **HTTPS 加密**：所有 API 请求必须通过 HTTPS 协议，确保数据传输的安全性。
|
||
- **令牌安全**：
|
||
- 认证令牌和访问令牌应保密存储，避免泄露。
|
||
- 令牌在传输过程中只能通过 `Authorization` 头部发送，避免在 URL 或请求体中传递。
|
||
- **权限控制**：
|
||
- 后端需要验证令牌的有效性和权限，防止未授权的访问。
|
||
- 管理员和客户用户的权限应严格区分，防止越权操作。
|
||
- **输入验证**：
|
||
- 对所有输入参数进行严格的格式和类型验证，防止 SQL 注入和 XSS 攻击。
|
||
- **错误信息**：
|
||
- 返回的错误信息应简洁明了，避免泄露服务器内部信息。
|
||
|
||
---
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 获取访问令牌示例
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /api/auth/token HTTP/1.1
|
||
Host: api.yourdomain.com
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"auth_token": "abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"access_token": "wxyz1234abcd5678efgh9012ijkl3456mnop7890qrst1234uvwx5678yzab9012",
|
||
"expires_in": 3600
|
||
}
|
||
```
|
||
|
||
### 8.2 发送提示词请求示例
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
POST /api/llm/request HTTP/1.1
|
||
Host: api.yourdomain.com
|
||
Content-Type: application/json
|
||
Authorization: Bearer wxyz1234abcd5678efgh9012ijkl3456mnop7890qrst1234uvwx5678yzab9012
|
||
|
||
{
|
||
"prompt": "Hello, how are you?"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"response": "I'm doing well, thank you for asking!"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 结论
|
||
|
||
本 API 开发文档详细描述了 LLM API 转发平台的各项接口、请求与响应格式、错误代码和安全性考虑。开发者应根据本规范进行接口的开发与测试，确保系统的稳定性和安全性。
|
||
|
||
---
|
||
|
||
**注意**：在实际开发中，可能需要根据具体的业务需求和技术选型，进一步完善和调整本 API 文档。
|
||
|
||
---
|
||
|
||
# 附录
|
||
|
||
## 技术栈说明
|
||
|
||
- **Laravel**：PHP 的优秀框架，提供了丰富的功能和高效的开发体验。
|
||
- **MySQL**：关系型数据库，存储平台的核心数据。
|
||
- **Redis**：高性能的内存缓存数据库，用于存储短期令牌和支持动态注销。
|
||
|
||
## 开发建议
|
||
|
||
- **代码规范**：遵循 Laravel 和 PHP 的代码规范，使用 PSR 标准。
|
||
- **日志记录**：重要的操作和错误需要记录日志，便于追踪和排查问题。
|
||
- **单元测试**：编写单元测试和集成测试，确保接口的稳定性和可靠性。
|
||
- **性能优化**：关注接口的性能，使用缓存、异步等方式优化响应速度。
|
||
|
||
---
|
||
|
||
**感谢阅读本 API 开发文档，如有任何疑问或建议，请与项目组联系。** |