评估 API

用于根据用户定义属性（例如响应清晰度、礼貌、倾听能力等）评估对话记录的 API。

此 API 仅适用于专业版及以上套餐。

Convai 的评估 API 端点

POST https://api.convai.com/character/evaluate_conversation

此 API 允许你根据用户定义的属性来评估对话记录，例如回复清晰度、礼貌程度、倾听能力等。评估结果将以结构化的 JSON 格式返回。

请求头

名称	类型	描述
CONVAI-API-KEY*	字符串	每个账户提供的唯一 API 密钥。

请求正文

名称	类型	描述
session_id	字符串（必填）	你想要评估的会话 ID。
character_id	字符串（必填）	执行评估的角色 ID。
提示词	字符串（必填）	一个预定义或自定义的提示词，包含对话记录和用于评估的具体说明。
变量	JSON 对象（可选）	一组键值对，提供评估所需的附加数据（例如，客户姓名、商品详情）。这取决于 提示词 所传入的内容。

示例载荷

{
  "session_id": "<SESSION ID>",
  "character_id": "<CHARACTER ID>",
  "prompt": "<EVALUATION PROMPT>",
  "variables": {
    "customer_name": "Suzie Denver",
    "customer_age": "54 岁",
    "item_details": [
      {
        "item": "汉堡",
        "price": "$4",
        "quantity": 3
      },
      {
        "item": "薯条",
        "price": "$2",
        "quantity": 2
      }
    ]
  }
}

示例提示词

你是一名被指定用于评估给定场景中员工-客户互动的人类分析员。根据下方提供的对话记录，分析这段互动，并按照指定属性给出评估。每个属性都应在 Excellent、Good、Fair 或 Needs Improvement 这四个等级中进行评分。请提供对话中的具体示例来支持你的评分。请以结构化 JSON 格式返回评估结果，以便于解析。
对话记录：
[[conversation_history]]


以下是评估对话可能需要的一些数据：
实际订单：[[item_details]]
客户姓名：[[customer_name]]
客户年龄：[[customer_age]]


请根据上面列出的属性评估上述对话，并为每个属性提供评分和反馈。如果某个属性不适用或无法评估，请在 json 输出中返回 null。请按以下格式返回结果：


{
  "evaluation": {
    "correctness_of_responses": {
      "rating": "",
      "feedback": "[员工是否根据客户的请求正确地下单了实际订单？]"
    },
    "clarity_of_responses": {
      "rating": "]",
      "feedback": "[根据提供的文本，员工的回复是否清晰且易于理解？]"
    },
    "conciseness_and_relevance": {
      "rating": "",
      "feedback": "[员工的回复是否简洁，并且聚焦于相关细节，而没有不必要的信息？]"
    },
    "courtesy_and_respect": {
      "rating": "",
      "feedback": "[员工在语言和回复中是否对客户表现出礼貌和尊重？]"
    },
    "listening_skills": {
      "rating": "",
      "feedback": "[员工是否做出了恰当回应，表明他们在主动倾听并处理客户的顾虑？]"
    },
    "product_knowledge": {
      "rating": "",
      "feedback": "[员工是否展现了对菜单、促销或政策的准确了解？]"
    },
    "problem_solving_and_issue_resolution": {
      "rating": "",
      "feedback": "[评估员工处理和解决问题的表现]"
    },
    "response_time": {
      "rating": "",
      "feedback": "[分析对话的流程，以及回复是否存在延迟]"
    },
    "order_accuracy": {
      "rating": "",
      "feedback": "[如适用，请评估订单确认的准确性]"
    },
    "follow_up_and_conversation_closure": {
      "rating": "",
      "feedback": "[查看对话是如何结束的，以及是否进行了适当的后续跟进]"
    },
    "overall_summary": {
      "overall_rating": "",
      "overall_feedback": "[请简要总结员工在所有属性方面的表现]"
    }
  }
}

如果你关注提示词，其中有某些文本位于 [[ ]] 。这些是 预期变量。现在， [[conversation_history]] 是一个必须出现在提示词中的必需预期变量。其余变量取决于你的需求，可按需传入提示词。

因此， 变量 请求体中的键应具有长度 expected-variables - 1，即应为在 [[ ]] 括号中提到的所有其他键提供值，除了 conversation_history 它是从 session_id 所提供的内容中获取的。该 变量 列表可以为空，如果你没有传入其他 预期变量 内容，则如此。

如果不传入 conversation_history 提示词中的变量，将导致服务器返回 500 错误响应。

响应

200：OK

成功后，API 会返回对话的结构化评估，涵盖多个属性。

{
  "evaluation": {
    "clarity_of_responses": {
      "rating": "Excellent",
      "feedback": "员工在整个对话过程中都提供了清晰且简洁的回复。"
    },
    "conciseness_and_relevance": {
      "rating": "Good",
      "feedback": "回复相关，但可以更简洁。"
    },
    "courtesy_and_respect": {
      "rating": "Excellent",
      "feedback": "员工礼貌且尊重他人。"
    },
    "listening_skills": {
      "rating": "Good",
      "feedback": "员工做出了恰当回应，不过有些顾虑是在延迟之后才得到处理。"
    },
    "product_knowledge": {
      "rating": "Excellent",
      "feedback": "员工展现了对菜单的准确了解。"
    },
    "problem_solving_and_issue_resolution": {
      "rating": "Needs Improvement",
      "feedback": "问题解决耗时比预期更长。"
    },
    "response_time": {
      "rating": "Fair",
      "feedback": "回复之间存在明显延迟。"
    },
    "order_accuracy": {
      "rating": "Excellent",
      "feedback": "所有项目都得到了准确确认。"
    },
    "follow_up_and_conversation_closure": {
      "rating": "Good",
      "feedback": "员工进行了适当的后续跟进，但收尾本可以更流畅。"
    },
    "overall_summary": {
      "overall_rating": "Good",
      "overall_feedback": "员工的表现总体良好，但在响应速度方面仍有改进空间。"
    }
  }
}

401：提供的 API 密钥无效

500：内部服务器错误

代码片段

import requests
import json

EVALUATION_URL = "https://api.convai.com/character/evaluate_conversation"

# 请求头
headers = {
  'Content-Type': 'application/json',
  'CONVAI-API-KEY': '<YOUR API KEY>'
}

# 请求体
payload = {
    "session_id": "<SESSION ID>",
    "character_id": "<CHARACTER ID>",
    "prompt": "<YOUR CUSTOM PROMPT>",
    "variables": {
        "customer_name": "Suzie Denver",
        "customer_age": "54 岁",
        "item_details": json.dumps([
            {"item": "汉堡", "price": "$4", "quantity": 3},
            {"item": "薯条", "price": "$2", "quantity": 2}
        ])
    }
}

# 发起请求
response = requests.post(EVALUATION_URL, headers=headers, json=payload)

# 处理响应
evaluation_response = response.json()

try:
    evaluation = evaluation_response["evaluation"]
    print("评估： ", evaluation)
except KeyError:
    print("错误： ", evaluation_response)