Chat System API 使用指南

安装和配置

1. 运行数据库迁移

php artisan migrate

2. 发布配置文件（如需要）

php artisan vendor:publish --provider="App\Providers\ChatServiceProvider"

API 端点和用法

聊天管理 API

1. 创建新聊天

POST /api/v2/chats
Content-Type: application/json

{
    "title": "天气查询对话",
    "user_id": "ba5463f3-72d1-4410-858e-eadd10884713"
}

响应示例:

{
  "ok": true,
  "message": "ok",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "天气查询对话",
    "user_id": "ba5463f3-72d1-4410-858e-eadd10884713",
    "created_at": "2025-01-15T10:30:00.000000Z",
    "updated_at": "2025-01-15T10:30:00.000000Z"
  }
}

2. 获取聊天列表

GET /api/v2/v2/chats?limit=20&user_id=123

3. 获取单个聊天详情

GET /api/v2/v2/chats/{chat_uid}

4. 更新聊天标题

PUT /api/v2/chats/{chat_uid}
Content-Type: application/json

{
    "title": "更新后的标题"
}

5. 删除聊天

DELETE /api/v2/chats/{chat_uid}

消息管理 API

消息不允许更新和删除，只能新建

1. 获取消息列表

GET /api/v2/chat-messages?chat=123

响应示例:

{
  "ok": true,
  "message": "ok",
  "data": {
    "rows": [
      {
        "id": 1,
        "uid": "message-1",
        "role": "user",
        "content": "查询今天北京的天气",
        "session_id": "session-1",
        "editor_id": "editor-uuid-456"
      },
      {
        "id": 2,
        "uid": "message-2",
        "session_id": "session-2",
        "parent_id": "message-1",
        "role": "assistant",
        "model_id": "gpt-4",
        "tool_calls": [
          {
            "id": "call_123",
            "function": "get_weather",
            "arguments": {
              "city": "北京",
              "date": "today"
            }
          }
        ]
      },
      {
        "id": 3,
        "uid": "message-3",
        "session_id": "session-2",
        "parent_id": "message-2",
        "role": "tool",
        "content": "今天北京天气晴朗，气温25°C，湿度60%，风力3级",
        "tool_call_id": "call_123"
      },
      {
        "id": 4,
        "uid": "message-4",
        "session_id": "session-2",
        "parent_id": "message-3",
        "role": "tool",
        "content": "今天北京天气晴朗，气温25°C，湿度60%，风力3级",
        "tool_call_id": "call_123",
        "model_id": "model-uuid-123",
        "metadata": {
          "temperature": 0.7,
          "tokens": 150,
          "max_tokens": 1000
        }
      }
    ],
    "total": 4
  }
}

1. 创建用户消息

POST /api/v2/chat-messages
Content-Type: application/json

{
    "chat_id":"1234",
    "messages": [
        {
            "role": "user",
            "content": "查询今天北京的天气"
        }
    ]

}

2. 创建带工具调用的 Assistant 消息

工具调用的 Assistant 消息,工具结果消息,最终回复消息，应该在结果正常返回后一次发送建立

POST /api/v2/chats/{chat_uid}/messages
Content-Type: application/json

{
    "chat_id":"1234",
    "messages": [
            {
                "parent_id": "user-message-uuid",
                "role": "assistant",
                "model_id": "gpt-4",
                "tool_calls": [
                    {
                        "id": "call_123",
                        "function": "get_weather",
                        "arguments": {
                            "city": "北京",
                            "date": "today"
                        }
                    }
                ]
            },
            {
                "parent_id": "assistant-message-uuid",
                "role": "tool",
                "content": "今天北京天气晴朗，气温25°C，湿度60%，风力3级",
                "tool_call_id": "call_123"
            },
            {
                "parent_id": "assistant-message-uuid",
                "role": "tool",
                "content": "今天北京天气晴朗，气温25°C，湿度60%，风力3级",
                "tool_call_id": "call_123"
            },
    ]
}

典型业务场景示例

场景 1: 完整的 Function Call 对话流程

// 1. 创建聊天
const chatResponse = await fetch("/api/v2/chats", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        title: "天气查询助手",
    }),
});
const chat = await chatResponse.json();

// 2. 用户提问
const userMessage = await fetch(`/api/v2/chat-messages`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        chat_id: "chat-id",
        messages: [
            {
                role: "user",
                content: "今天上海天气怎么样？",
            },
        ],
    }),
});
const userMsg = await userMessage.json();

// 3. Assistant 调用工具

const assistantCall = await fetch(`/api/v2/chats-messages`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        chat_id: "chat-id",
        messages: [
            {
                parent_id: userMsg.data.id,
                role: "assistant",
                model_name: "gpt-4",
                tool_calls: [
                    {
                        id: "call_weather_001",
                        function: "get_weather",
                        arguments: { city: "上海", date: "today" },
                    },
                ],
            },
            {
                parent_id: assistantMsg.data.id,
                role: "tool",
                content: "上海今日天气：晴，22-28°C，东南风3级，湿度65%",
                tool_call_id: "call_weather_001",
            },
            {
                parent_id: toolMsg.data.id,
                role: "assistant",
                content:
                    "今天上海的天气很不错！晴天，气温在22-28度之间，很适合外出。东南风3级，体感舒适，湿度适中。建议穿轻薄的长袖或短袖都可以。",
                model_id: 'model-uuid-123',
                metadata: {
                    temperature: 0.7,
                    tokens: 150,
                    max_tokens: 1000
                },
            },
        ],
    }),
});
const assistantMsg = await assistantCall.json();



## 数据模型说明

### Chat 模型

-   `id`: 数据库自增 ID
-   `uid`: UUID 标识符，用于 API 调用
-   `title`: 聊天标题
-   `user_id`: 用户 ID（可选）
-   `created_at/updated_at`: 时间戳

### ChatMessage 模型

-   `id`: 数据库自增 ID（用于版本排序，替代 version 字段）
-   `uid`: UUID 标识符，用于 API 调用
-   `chat_id`: 所属聊天 ID
-   `parent_id`: 父消息 UUID（构建依赖关系）
-   `session_id`: 会话组 UUID（前端显示分组）
-   `role`: 消息角色（user/assistant/tool）
-   `content`: 消息内容
-   `model_id`: 使用的 AI 模型 UUID
-   `tool_calls`: 工具调用信息（JSON 格式）
-   `tool_call_id`: 工具调用 ID（tool 消息专用）
-   `metadata`: 元数据信息（temperature、tokens 等，JSON 格式）
-   `editor_id`: 编辑者 UUID
-   `is_active`: 是否为当前激活版本

## 重要变更说明

### 1. 版本控制机制改变

-   **移除**: `version`字段
-   **新机制**: 使用数据库自增 ID 自然排序实现版本控制
-   **优势**: 避免多浏览器并发冲突，ID 天然递增保证版本顺序

### 2. 新增字段

-   `metadata`: JSON 字段存储模型参数和执行信息
-   `editor_id`: UUID 字段记录编辑者信息
-   `model_id`: 改为 UUID 格式，便于模型管理

### 3. 字段类型调整

-   `user_id`: 从 BIGINT 改为 UUID 格式
-   `model_name` → `model_id`: 名称改为 UUID 引用

## 错误处理

API 使用标准 HTTP 状态码：

-   `200`: 操作成功
-   `201`: 资源创建成功
-   `400`: 请求参数错误
-   `404`: 资源不存在
-   `422`: 验证失败
-   `500`: 服务器错误

错误响应格式：

```json
{
    "ok":false,
    "message": "错误描述",
    "errors": {
        "field_name": ["具体错误信息"]
    }
}

性能优化建议

分页查询: 大量消息时使用分页参数limit
索引优化: 数据库已包含必要索引
缓存策略: 对频繁查询的聊天历史考虑使用 Redis 缓存
批量操作: 使用批量更新 API 减少网络请求
懒加载: 前端可按需加载消息版本和历史记录

安全考虑

权限验证: 根据需要添加用户认证中间件
输入验证: 所有输入都经过 FormRequest 验证
SQL 注入防护: 使用 Eloquent ORM 和参数化查询
XSS 防护: 输出时进行适当转义
CSRF 保护: API 接口建议配置 CSRF 中间件

扩展功能

系统支持以下扩展：

多用户支持: 通过 user_id 字段隔离数据
消息搜索: 可在 content 字段上建立全文索引
文件附件: content 字段支持 JSON 格式存储多媒体内容
消息导出: 可导出完整对话历史

api.md 9.2 KB Istoric Crud

Chat System API 使用指南

安装和配置

1. 运行数据库迁移

2. 发布配置文件（如需要）

API 端点和用法

聊天管理 API

1. 创建新聊天

2. 获取聊天列表

3. 获取单个聊天详情

4. 更新聊天标题

5. 删除聊天

消息管理 API

1. 获取消息列表

1. 创建用户消息

2. 创建带工具调用的 Assistant 消息

典型业务场景示例

场景 1: 完整的 Function Call 对话流程

性能优化建议

安全考虑

扩展功能

api.md 9.2 KB

Istoric Crud