> 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

{% 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 密钥。 |

### 请求正文

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

### 示例载荷

```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
你是一名被指定用于评估给定场景中员工-客户互动的人类分析员。根据下方提供的对话记录，分析这段互动，并按照指定属性给出评估。每个属性都应在 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": "[请简要总结员工在所有属性方面的表现]"
    }
  }
}
```

{% endcode %}

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

因此， `变量` 请求体中的键应具有长度 `expected-variables - 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": "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": "员工的表现总体良好，但在响应速度方面仍有改进空间。"
    }
  }
}

```

<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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.