webpage_parse_api_文档.md 9.8 KB
网页文本解析API接口文档
接口概述
接口名称: 网页文本解析接口
接口路径: /api/data-parse/webpage-parse
请求方法: POST
内容类型: application/json
功能描述: 解析网页Markdown文本并使用QWen AI模型提取人员任命信息
输入参数
请求头
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Content-Type | string | 是 | 必须为 application/json |
请求体参数
| 参数名 | 类型 | 必填 | 长度限制 | 说明 |
|---|---|---|---|---|
| markdown_text | string | 是 | 10-50000字符 | 网页的Markdown格式文本内容 |
| publish_time | string | 是 | - | 发布时间，用于设置career_path中的date字段，建议格式：YYYY-MM-DD |
请求体示例
{
"markdown_text": "\n\n**张三先生**\n**Mr. Zhang San**\n\n北京万豪酒店\n总经理\n\n张三先生拥有15年酒店管理经验...",
"publish_time": "2025-01-15"
}
输出参数
响应格式
所有响应均为JSON格式，包含以下基本结构：
{
"success": boolean,
"message": string,
"data": array|null
}
成功响应 (200)
{
"success": true,
"message": "网页文本解析成功",
"data": [
{
"name_zh": "张三",
"name_en": "Zhang San",
"title_zh": "总经理",
"title_en": "General Manager",
"hotel_zh": "北京万豪酒店",
"hotel_en": "Beijing Marriott Hotel",
"brand_group": "万豪",
"pic_url": "https://example.com/photo.jpg",
"career_path": [
{
"date": "2025-01-15",
"hotel_en": "Beijing Marriott Hotel",
"hotel_zh": "北京万豪酒店",
"image_path": "",
"source": "webpage_extraction",
"title_en": "General Manager",
"title_zh": "总经理"
}
]
}
]
}
数据字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| name_zh | string | 人员中文姓名 |
| name_en | string | 人员英文姓名 |
| title_zh | string | 中文职位/头衔 |
| title_en | string | 英文职位/头衔 |
| hotel_zh | string | 中文酒店/公司名称 |
| hotel_en | string | 英文酒店/公司名称 |
| brand_group | string | 酒店品牌集团 |
| pic_url | string | 人员照片URL链接 |
| career_path | array | 职业轨迹数组 |
career_path 对象说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| date | string | 任命日期 (使用传入的publish_time) |
| hotel_en | string | 英文酒店名称 |
| hotel_zh | string | 中文酒店名称 |
| image_path | string | 图片路径 (固定为空字符串) |
| source | string | 数据来源 (固定为"webpage_extraction") |
| title_en | string | 英文职位 |
| title_zh | string | 中文职位 |
错误响应
400 - 请求参数错误
缺少必填参数
{
"success": false,
"message": "缺少必填参数: markdown_text",
"data": null
}
参数类型错误
{
"success": false,
"message": "markdown_text 必须是字符串类型",
"data": null
}
内容长度错误
{
"success": false,
"message": "markdown_text 内容过长，最大支持50KB",
"data": null
}
请求格式错误
{
"success": false,
"message": "请求必须是 JSON 格式",
"data": null
}
500 - 服务器内部错误
{
"success": false,
"message": "网页文本解析失败: 具体错误信息",
"data": null
}
状态码说明
| 状态码 | 说明 | 响应示例 |
|---|---|---|
| 200 | 解析成功 | 返回提取的人员信息数据 |
| 400 | 请求参数错误 | 参数缺失、类型错误、内容格式问题等 |
| 500 | 服务器内部错误 | AI模型调用失败、系统异常等 |
使用说明
1. 环境要求
- 需要配置
QWEN_API_KEY环境变量 - 服务器需要能访问阿里云QWen API
2. 支持的内容格式
- 支持标准Markdown格式文本
- 支持提取照片链接（
格式） - 支持中英文混合内容
- 支持多人员信息提取
3. 内容长度限制
- 最小长度：10字符
- 最大长度：50,000字符 (约50KB)
4. 最佳实践
- 提供结构化的Markdown内容以获得更好的提取效果
- 照片链接应放置在人员姓名前面，通过空行分隔
- 使用标准的日期格式 (YYYY-MM-DD) 作为 publish_time
测试样例
样例1：单人信息提取
请求:
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
-H "Content-Type: application/json" \
-d '{
"markdown_text": "\n\n**周银萍 女士**\n**Ms. Sandra Zhou**\n\n深圳中洲万豪酒店\n人力资源总监\n\n近日，深圳中洲万豪酒店正式任命周银萍女士为酒店人力资源总监...",
"publish_time": "2025-01-15"
}'
响应:
{
"success": true,
"message": "网页文本解析成功",
"data": [
{
"name_zh": "周银萍",
"name_en": "Sandra Zhou",
"title_zh": "人力资源总监",
"title_en": "Director of Human Resources",
"hotel_zh": "深圳中洲万豪酒店",
"hotel_en": "Shenzhen Marriott Hotel Nanshan",
"brand_group": "万豪",
"pic_url": "https://example.com/sandra.jpg",
"career_path": [
{
"date": "2025-01-15",
"hotel_en": "Shenzhen Marriott Hotel Nanshan",
"hotel_zh": "深圳中洲万豪酒店",
"image_path": "",
"source": "webpage_extraction",
"title_en": "Director of Human Resources",
"title_zh": "人力资源总监"
}
]
}
]
}
样例2：多人信息提取
请求:
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
-H "Content-Type: application/json" \
-d '{
"markdown_text": "**1**\n\n\n\n**曲晶 女士**\n\n诺金国际\n市场营销副总裁\n\n**2**\n\n\n\n**扎西央宗 女士**\n\n北海涠洲岛悦苑酒店\n总经理",
"publish_time": "2025-01-15"
}'
响应:
{
"success": true,
"message": "网页文本解析成功",
"data": [
{
"name_zh": "曲晶",
"name_en": "",
"title_zh": "市场营销副总裁",
"title_en": "",
"hotel_zh": "诺金国际",
"hotel_en": "",
"brand_group": "诺金",
"pic_url": "https://example.com/photo1.jpg",
"career_path": [...]
},
{
"name_zh": "扎西央宗",
"name_en": "",
"title_zh": "总经理",
"title_en": "",
"hotel_zh": "北海涠洲岛悦苑酒店",
"hotel_en": "",
"brand_group": "悦榕",
"pic_url": "https://example.com/photo2.jpg",
"career_path": [...]
}
]
}
样例3：参数错误
请求:
curl -X POST http://localhost:5000/api/data-parse/webpage-parse \
-H "Content-Type: application/json" \
-d '{
"markdown_text": "内容太短"
}'
响应:
{
"success": false,
"message": "缺少必填参数: publish_time",
"data": null
}
开发指南
Python 示例
import requests
import json
def parse_webpage_text(markdown_text, publish_time):
url = "http://localhost:5000/api/data-parse/webpage-parse"
headers = {"Content-Type": "application/json"}
data = {
"markdown_text": markdown_text,
"publish_time": publish_time
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# 使用示例
result = parse_webpage_text("网页内容...", "2025-01-15")
if result["success"]:
print(f"成功提取 {len(result['data'])} 个人员信息")
else:
print(f"提取失败: {result['message']}")
JavaScript 示例
async function parseWebpageText(markdownText, publishTime) {
const response = await fetch('/api/data-parse/webpage-parse', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
markdown_text: markdownText,
publish_time: publishTime
})
});
return await response.json();
}
// 使用示例
parseWebpageText("网页内容...", "2025-01-15")
.then(result => {
if (result.success) {
console.log(`成功提取 ${result.data.length} 个人员信息`);
} else {
console.error(`提取失败: ${result.message}`);
}
});
注意事项
- API密钥: 确保服务器已正确配置
QWEN_API_KEY环境变量 - 网络访问: 服务器需要能够访问阿里云QWen API服务
- 内容质量: 提供结构化、清晰的Markdown内容可以获得更好的提取效果
- 并发限制: 建议控制并发请求数量，避免超出API调用限制
- 错误处理: 建议在客户端实现适当的错误处理和重试机制
- 数据验证: 建议对返回的数据进行二次验证，确保提取质量
更新日志
版本 2.0 (2025-01-15)
- 新增
publish_time必填参数 - 更新 career_path 中 date 字段的设置逻辑
- 增强参数验证和错误处理
- 更新API文档和使用示例
版本 1.0 (初始版本)
- 基础的网页文本解析功能
- 支持单人和多人信息提取
- 集成QWen AI模型