TanWenyan/leaudit-platform-frontend

Fork 0

Files

T

LiangShiyong 3d1dbb3f97 all in

2025-12-05 00:09:32 +08:00

14 KiB

Raw Blame History

提示词模板管理 API 文档

供前端对接使用 | 更新时间：2025-11-27

概述

提示词模板管理模块提供对 prompt_templates 表的完整 CRUD 操作，用于管理 LLM/VLM 抽取、评查、摘要等场景的提示词模板。

基础路径: /api/v3/prompt-templates

认证方式: Bearer Token (JWT)

快速开始

典型前端页面流程

1. 页面加载 → 调用 GET /types 获取类型列表（用于筛选下拉框）
2. 列表展示 → 调用 GET / 获取模板列表（支持分页、筛选、搜索）
3. 查看详情 → 调用 GET /{id} 获取完整模板内容
4. 编辑保存 → 调用 PUT /{id} 更新模板
5. 创建模板 → 调用 POST / 或 POST /{id}/duplicate 复制
6. 删除模板 → 调用 DELETE /{id}

字段说明

template_type（模板类型）

用于标识模板的业务用途类别，支持按类型筛选。

值	显示名称	说明
`LLM_Extraction`	LLM抽取	LLM文档内容抽取
`VLM_Extraction`	VLM抽取	VLM图像识别抽取
`Summary`	摘要生成	文档摘要生成
`Evaluation`	评查	评查规则判断
`Directory_Extraction`	目录抽取	卷宗目录提取
`CaseNum_Extraction`	案号抽取	案件编号提取
`Contract_Directory_Extraction`	合同目录抽取	合同目录提取
`Contract_Number`	合同编号抽取	合同编号提取
`Contract_Compare`	合同比对	合同差异比对
`Parties_Extraction`	当事人抽取	当事人信息提取
`Common`	通用	通用模板

template_code（模板代码）

模板的唯一标识符，用于在配置中引用模板。

格式要求：英文字母、数字、下划线，最大50字符
示例：vlm_default_prompt, llm_general_extract, vlm_currency_prompt

status（状态）

值	说明	前端显示建议
`0`	停用	灰色标签 "停用"
`1`	启用	绿色标签 "启用"
`2`	系统预设	蓝色标签 "系统" + 禁用编辑/删除按钮

variables（变量定义）

定义模板中可替换的变量，格式为 JSON 对象。

{
    "doc_name": "文档名称",
    "json_template": "JSON输出模板",
    "field_list": "字段列表"
}

模板内容中使用 {变量名} 引用变量，如：请分析{doc_name}中的内容...

API 接口详细

1. 获取模板列表

用于列表页展示，支持分页、筛选、搜索。

请求

GET /api/v3/prompt-templates?page=1&page_size=20&template_type=VLM_Extraction&status=1&search=通用
Authorization: Bearer {token}

查询参数

参数	类型	必填	默认值	说明
page	int	否	1	页码，从1开始
page_size	int	否	20	每页数量，最大100
template_type	string	否	-	模板类型筛选
status	int	否	-	状态筛选（0/1/2）
search	string	否	-	模糊搜索（匹配名称或代码）

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "total": 25,
        "page": 1,
        "page_size": 20,
        "items": [
            {
                "id": 7,
                "template_name": "VLM通用卷宗抽取Prompt",
                "template_code": "vlm_default_prompt",
                "template_type": "VLM_Extraction",
                "description": "通用VLM图像抽取模板",
                "template_abbreviation": null,
                "status": 1,
                "created_by": 1,
                "created_at": "2025-01-15T10:30:00",
                "updated_at": "2025-01-20T14:20:00"
            }
        ]
    }
}

前端表格列建议

列名	字段	宽度	说明
ID	id	80px	可排序
模板名称	template_name	200px	可搜索
模板代码	template_code	180px	可复制
类型	template_type	120px	显示为标签
状态	status	80px	显示为标签
更新时间	updated_at	160px	格式化显示
操作	-	150px	查看/编辑/复制/删除

权限要求: prompt_template:list:read

2. 获取模板类型列表

用于筛选下拉框，返回所有类型及其数量。

请求

GET /api/v3/prompt-templates/types
Authorization: Bearer {token}

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "items": [
            {"value": "VLM_Extraction", "label": "VLM抽取", "count": 8},
            {"value": "LLM_Extraction", "label": "LLM抽取", "count": 5},
            {"value": "Summary", "label": "摘要生成", "count": 2},
            {"value": "Evaluation", "label": "评查", "count": 2}
        ]
    }
}

前端下拉框渲染

// 示例：Ant Design Select
<Select placeholder="选择模板类型">
    {types.map(item => (
        <Option key={item.value} value={item.value}>
            {item.label} ({item.count})
        </Option>
    ))}
</Select>

权限要求: prompt_template:list:read

3. 获取模板详情

用于查看/编辑页面，返回完整模板内容。

请求

GET /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 7,
        "template_name": "VLM通用卷宗抽取Prompt",
        "template_code": "vlm_default_prompt",
        "template_type": "VLM_Extraction",
        "template_content": "请分析以下图片内容，按照指定的JSON格式提取{doc_name}的信息...",
        "description": "通用VLM图像抽取模板",
        "template_abbreviation": null,
        "variables": {
            "doc_name": "文档名称",
            "json_template": "JSON模板"
        },
        "status": 1,
        "is_active": true,
        "created_by": 1,
        "created_at": "2025-01-15T10:30:00",
        "updated_at": "2025-01-20T14:20:00"
    }
}

权限要求: prompt_template:detail:read

4. 通过代码获取模板

用于通过 template_code 获取模板（配置引用时使用）。

请求

GET /api/v3/prompt-templates/code/{template_code}
Authorization: Bearer {token}

示例

GET /api/v3/prompt-templates/code/vlm_default_prompt

响应

同"获取模板详情"

权限要求: prompt_template:detail:read

5. 创建模板

请求

POST /api/v3/prompt-templates
Authorization: Bearer {token}
Content-Type: application/json

请求体

{
    "template_name": "自定义VLM抽取模板",
    "template_code": "custom_vlm_extract",
    "template_type": "VLM_Extraction",
    "template_content": "请分析图片中的{doc_name}，提取以下信息：\n{json_template}",
    "description": "针对特定场景优化的VLM抽取模板",
    "template_abbreviation": "自定义VLM",
    "variables": {
        "doc_name": "文档名称",
        "json_template": "JSON模板结构"
    },
    "status": 1
}

字段说明

字段	类型	必填	最大长度	说明
template_name	string	✅	255	模板名称
template_code	string	✅	50	模板代码（唯一）
template_type	string	✅	50	模板类型
template_content	string	✅	-	模板内容（prompt文本）
description	string	❌	-	模板描述
template_abbreviation	string	❌	100	模板简称
variables	object	❌	-	变量定义
status	int	❌	-	状态，默认1（启用）

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 73,
        "template_name": "自定义VLM抽取模板",
        "template_code": "custom_vlm_extract",
        "template_type": "VLM_Extraction",
        "status": 1,
        "created_at": "2025-11-26T10:00:00"
    }
}

错误情况

错误	HTTP状态码	message
模板代码已存在	400	模板代码已存在: xxx
缺少必填字段	422	field required

权限要求: prompt_template:create:write

6. 更新模板

请求

PUT /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}
Content-Type: application/json

请求体（所有字段可选，只传需要更新的字段）

{
    "template_name": "更新后的模板名称",
    "template_content": "更新后的模板内容...",
    "description": "更新后的描述",
    "status": 0
}

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 73,
        "template_name": "更新后的模板名称",
        "template_code": "custom_vlm_extract",
        "status": 0,
        "updated_at": "2025-11-26T11:00:00"
    }
}

注意事项

⚠️ 系统预设模板（status=2）不可修改，会返回403错误
修改 template_code 时会检查唯一性
不能将普通模板的 status 改为 2（系统预设）

权限要求: prompt_template:update:write

7. 删除模板

请求

DELETE /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}

响应

{
    "code": 200,
    "message": "success",
    "data": {
        "message": "提示词模板删除成功: 自定义VLM抽取模板"
    }
}

注意事项

⚠️ 系统预设模板（status=2）不可删除，会返回403错误
建议删除前显示确认对话框

权限要求: prompt_template:delete:delete

8. 复制模板

快速基于现有模板创建副本。

请求

POST /api/v3/prompt-templates/{template_id}/duplicate?new_code=my_custom_code
Authorization: Bearer {token}