消费凭证核验接口文档

概述

消费凭证核验接口提供用户上传消费凭证图片（小票、支付记录、订单截图等）的核验能力，系统使用视觉模型（Qwen3-VL-8B-Thinking）分析图片，判断是否为真实消费凭证。仅核验通过的用户才允许进行评论。

接口采用异步非阻塞设计，使用线程池执行模型调用，避免阻塞FastAPI事件循环，支持高并发场景。

基础URL

所有接口需要通过 9000网关 进行访问：

环境	基础URL
开发环境	`http://localhost:9000/multimodal_services/api/v1/consumption-proof`
生产环境	`http://<gateway-host>:9000/multimodal_services/api/v1/consumption-proof`

Content-Type: application/json

服务路由说明

网关端口: 9000
服务名: multimodal_services
服务端口: 9009
API版本: v1
接口前缀: /consumption-proof

完整URL路径示例

接口	完整URL路径（通过网关）
消费凭证核验	`http://localhost:9000/multimodal_services/api/v1/consumption-proof/verify`

⚠️ 注意: 请确保URL路径正确，避免重复路径段

接口列表

序号	接口	方法	路径	说明
1	消费凭证核验	POST	`/verify`	上传消费凭证图片URL列表，核验是否为真实凭证（可选：核验商户是否匹配）

1. 消费凭证核验

请求

POST /verify

请求参数

参数名	类型	必填	默认值	说明
image_urls	string[]	是	-	消费凭证图片URL列表（如小票、支付记录、订单截图等），1～10张
store_name	string	否	""	店铺名；若填写则核验凭证中的商户/店铺是否与该店铺一致

请求示例

{
    "image_urls": [
        "https://example.com/receipt1.jpg",
        "https://example.com/payment_record.png"
    ],
    "store_name": "某某餐厅"
}

响应参数

参数名	类型	说明
code	integer	响应状态码，200表示成功
message	string	响应消息
data	object	核验结果数据
data.can_comment	boolean	是否允许评论（仅当为真实消费凭证时为true）
data.is_valid_proof	boolean	是否为真实消费凭证
data.proof_type	string/null	识别到的凭证类型，如"小票"、"支付记录"、"订单截图"等
data.reason	string	核验结论说明
data.image_results	array	每张图片的核验结果列表
data.image_results[].image_index	integer	图片序号（从1开始）
data.image_results[].is_valid_proof	boolean	该图片是否为有效凭证
data.image_results[].proof_type	string	该图片识别到的凭证类型
data.image_results[].confidence	string	置信度，如"高"、"中"、"低"
data.image_results[].reason	string	该图片的核验说明
data.error	string	异常或错误信息，成功时为空
timestamp	float	响应时间戳（Unix时间戳）

成功响应示例

{
    "code": 200,
    "message": "操作成功",
    "data": {
        "can_comment": true,
        "is_valid_proof": true,
        "proof_type": "小票",
        "reason": "图片为真实消费小票，信息清晰可辨，且商户名称与店铺名一致",
        "image_results": [
            {
                "image_index": 1,
                "is_valid_proof": true,
                "proof_type": "小票",
                "confidence": "高",
                "reason": "包含商户（某某餐厅）、金额、时间等消费信息"
            },
            {
                "image_index": 2,
                "is_valid_proof": false,
                "proof_type": "",
                "confidence": "",
                "reason": "图片模糊，无法识别有效信息"
            }
        ],
        "error": ""
    },
    "timestamp": 1704067200.123
}

失败响应示例

参数校验失败（422）

{
    "code": 422,
    "message": "请求参数不合法",
    "data": null,
    "details": {
        "errors": [
            {
                "loc": ["image_urls"],
                "msg": "ensure this value has at least 1 items",
                "type": "value_error.list.min_items"
            }
        ]
    },
    "timestamp": 1704067200.456
}

业务异常（400）

{
    "code": 400,
    "message": "图片URL列表为空",
    "data": null,
    "details": {
        "data": {
            "can_comment": false,
            "is_valid_proof": false,
            "proof_type": null,
            "reason": "",
            "image_results": [],
            "error": "图片URL列表为空"
        }
    },
    "timestamp": 1704067200.789
}

服务异常（500）

{
    "code": 500,
    "message": "服务暂时不可用，请稍后重试",
    "data": null,
    "details": null,
    "timestamp": 1704067200.012
}

业务逻辑说明

核验流程

参数校验：检查image_urls是否为空，数量是否在1～10之间
构建Prompt：根据图片数量和店铺名构建核验提示词
模型调用：使用Qwen3-VL-8B-Thinking视觉模型分析图片（在线程池中执行，不阻塞事件循环）
结果解析：解析模型返回的JSON，提取核验结果
结果判定：
- is_valid_proof为true时，can_comment为true，允许评论
- is_valid_proof为false时，can_comment为false，不允许评论
- 若填写了store_name，还会核验凭证中的商户名称是否与店铺名一致

支持的凭证类型

消费小票/发票
支付记录截图
订单截图
其他包含消费信息的凭证

模型判断依据

模型会分析图片中的以下内容：

商户名称（若填写store_name，核验是否匹配）
消费金额
交易时间
订单号/流水号
其他消费相关信息

注意事项

网关访问：所有接口必须通过9000网关访问，URL格式为 http://<gateway>:9000/multimodal_services/api/v1/consumption-proof/...，直接访问9009端口不推荐。
图片要求：
- 图片URL必须可公开访问
- 建议上传清晰、完整的凭证图片
- 支持的图片格式：jpg、png等常见格式
数量限制：
- 最少上传1张图片
- 最多上传10张图片
店铺名匹配：
- store_name参数为可选
- 若填写，模型会核验凭证中的商户名称是否与该店铺名一致
- 有助于确保用户确实在该店铺消费
响应时间：
- 模型推理需要一定时间，请合理设置超时时间（建议10～30秒）
幂等性：
- 该接口为查询类接口，可重复调用获取相同结果

小票审核接口.md 6.8 KB Pysyvä linkki Historia Raaka