> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/evaluation-api.md).

# 评估 API

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

{% hint style="danger" %}
此 API 仅适用于专业版及以上计划。
{% endhint %}

## Convai 的评估 API 端点

<mark style="color:绿色;">POST</mark> `https://api.convai.com/character/evaluate_conversation`

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

### 请求头

| 名称                                              | 类型  | 说明                  |
| ----------------------------------------------- | --- | ------------------- |
| CONVAI-API-KEY<mark style="color:红色;">\*</mark> | 字符串 | 适用于每个账户的唯一 api-key。 |

### 请求体

| 名称            | 类型          | 说明                                                 |
| ------------- | ----------- | -------------------------------------------------- |
| session\_id   | 字符串（必填）     | 您要评估的会话 ID。                                        |
| character\_id | 字符串（必填）     | 执行评估的角色 ID。                                        |
| prompt        | 字符串（必填）     | 包含对话记录和具体评估说明的预定义或自定义提示。                           |
| 变量            | JSON 对象（可选） | 提供评估所需附加数据的一组键值对（例如，客户姓名、商品详情）。这取决于 `prompt` 正在传入。 |

### 示例负载

```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
      }
    ]
  }
}
```

#### 示例提示

{% code overflow="wrap" %}

```json
你是一名人类分析师，负责评估给定场景中的员工与客户互动。根据下面提供的对话记录，分析此次互动，并根据指定属性给出评估。每个属性都应按“优秀、良好、一般或需改进”的等级进行评分。请提供对话中的具体示例来支持你的评分。请以结构化 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": "[请简要总结员工在所有属性上的表现]"
    }
  }
}
```

{% endcode %}

{% hint style="info" %}
如果你关注提示，其中有某些文本位于 `[[ ]]` 。这些是 `预期变量`。现在， `[[conversation_history]]` 是一个必须存在于提示中的必需预期变量。其余变量则取决于你的需求，可按需传入提示。

因此 `变量` 请求体中的键长度应为 `预期变量 - 1`，即，除了在 `[[ ]]` 括号中提到的所有其他键都应有值，除了 `conversation_history` 它是从 `session_id` 提供的。该 `变量` 列表可以为空，如果你没有传递其他 `预期变量` 到提示中。
{% endhint %}

{% hint style="danger" %}
不传递 `conversation_history` 变量到提示中将导致服务器返回 500 错误响应。
{% endhint %}

### 响应

{% tabs %}
{% tab title="200: OK" %}
成功时，API 会返回对话的结构化评估，涵盖多个属性。

```json
{
  "evaluation": {
    "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": "员工的整体表现总体不错，但在响应速度方面仍有提升空间。"
    }
  }
}

```

<br>
{% endtab %}

{% tab title="401：提供的 API 密钥无效" %}

```json
{
    "ERROR": "提供的 API 密钥无效。"
}
```

{% endtab %}

{% tab title="500：内部服务器错误" %}

```json
{
    "ERROR": "变量列表无效。请重新检查正在发送的变量",
    "Reference ID": "<REFERENCE-ID>"
}
```

{% endtab %}
{% endtabs %}

### 代码片段

```python
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)

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/evaluation-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.