> 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 仅适用于 Professional 计划及更高级别的计划。
{% 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   | String（必填）  | 要评估的会话 ID。                                          |
| character\_id | String（必填）  | 执行评估的角色 ID。                                         |
| prompt        | String（必填）  | 包含对话记录和具体评估说明的预定义或自定义提示词。                           |
| variables     | JSON 对象（可选） | 提供评估所需附加数据（例如客户姓名、商品详情）的一组键值对。具体内容取决于传入的 `prompt` 。 |

### 请求示例

```json
{
  "session_id": "<SESSION ID>",
  "character_id": "<CHARACTER ID>",
  "prompt": "<EVALUATION PROMPT>",
  "variables": {
    "customer_name": "Suzie Denver",
    "customer_age": "54 years",
    "item_details": [
      {
        "item": "Burger",
        "price": "$4",
        "quantity": 3
      },
      {
        "item": "Fries",
        "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" %}
如果仔细查看提示词，其中有一些文本位于 `[[ ]]` 之中。这些文本是 `expected-variables`。现在， `[[conversation_history]]` 是必须提供的预期变量，必须包含在提示词中。其余变量可根据需要传入提示词。

因此， `variables` 请求正文中的键，其长度应为 `expected-variables - 1`，也就是说，除了 `[[ ]]` 外，提示词中方括号内提及的所有其他键都应提供相应的值； `conversation_history` 会从提供的 `session_id` 中获取。如果没有传入其他 `variables` ，则列表可以为空。 `expected-variables` 。
{% endhint %}

{% hint style="danger" %}
如果未在提示词中传入 `conversation_history` 变量，服务器将返回 500 错误。
{% endhint %}

### 响应

{% tabs %}
{% tab title="200：成功" %}
成功时，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 years",
        "item_details": json.dumps([
            {"item": "Burger", "price": "$4", "quantity": 3},
            {"item": "Fries", "price": "$2", "quantity": 2}
        ])
    }
}

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

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

try:
    evaluation = evaluation_response["evaluation"]
    print("Evaluation: ", evaluation)
except KeyError:
    print("Error: ", 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.
