# 角色模拟能力使用说明

# 概念术语

●应用，即集成角色模拟服务的第三方应用程序。您需要在讯飞开放平台注册您的应用程序，获取唯一的身份凭证，作为后续调用 API 时的认证依据。

●玩家，即与角色对话的终端用户。您需要为每一位使用对话功能的用户创建玩家帐号。除非您在应用层自定义了特殊逻辑，否则默认情况下，每个玩家都可以与应用下的任意角色进行对话。

●角色，即人格。角色必须创建在某个玩家帐号下。您可以使用固定的玩家帐号来集中管理所有角色，也可以允许玩家自定义角色，将角色创建在不同玩家帐号下。

●会话，包含一轮或多轮对话。玩家退出对话功能时，视为本次会话的终结。当玩家再次访问对话功能时，视为新会话的开始。

●对话，包含一次玩家的输入，和一次角色模拟服务的对话输出。

●短期记忆，包含对话记忆和观察记忆。
○对话记忆指，玩家和角色经历的每一轮对话。对话记忆将持续影响角色的后续对话及行为反应。对话记忆由我们的服务自动创建。 ○观察记忆指，角色视角下的剧情场景、背景知识、对话人身份信息等。您可以在调用对话接口前，为角色创建一条观察记忆，帮助角色了解场景上下文，并按照剧情展开对话。

# 使用流程

创建应用 -> 开通服务（领取试用包或购买套餐）-> 创建玩家帐号 -> 创建角色（人格） -> 生成对话

# 生成对话流程

1.注册玩家帐号
您需要为每一位使用对话功能的用户创建玩家帐号。
涉及接口：player/if_register()、player/register()

2.（可选）初始化对话场景
您可以在每次会话开启前，为角色创建一条“短期记忆”，帮助角色理解当前对话的场景或前情提要。
涉及接口：interactive/generate

3.（可选）发起对话
您可以使用这项特性，创作角色“主动”向玩家发言的效果。
涉及接口：interactivews

4.响应对话
当玩家发言后，驱动角色回应
涉及接口：interactivews

5.（可选）全新会话
当角色生成的对话出现重复生成等异常时，您可以使用这项功能，清除角色模拟服务缓存中的对话历史，对角色进行重置。
涉及接口：interaction/clear-cache

# 计量规则

# 字符统计规则

我们的服务使用 Java 'String.length()' 方法统计对话用量，即统计字符串中 UTF-16 编码单元的数量。

如您使用 word 等第三方工具进行用量统计，会发生统计偏差的现象。原因可能包括：
●您使用的工具仅统计可见字符的数量，遗漏了换行符、特殊符号等。
●换行符会由我们的程序进行转义，转义后的字符表示为“\n”，计为1。但您使用的工具可能将转义换行符计为2。

# 计费项统计规则

角色模拟服务将基于每一轮对话所消耗的字数total_chars进行收费，计费项包含角色设定字数+对话字数。

# 角色设定字数

这是由您预先设定的角色描述信息带来的字数开销。
角色描述信息包括名称、职业身份、性格、爱好等，会经由我们的服务转化成模型可理解的格式化指令。每一轮对话的生成，都需要将这部分信息转化为指令，并传输给模型以维持人设。指令字数即角色设定字数，在接口返回时以system_current_chars表示。

# 对话字数

对话字数包含三部分：
●用户输入的字数
●角色输出的字数
●角色记忆中的历史对话字数
用户输入的字数，和角色输出的字数是显而易见的。而角色记忆则是为了保持上下文的连贯性，我们的服务会根据您购买的套餐设定，记录一定轮数的先前对话内容，以指导当前的对话生成。
历史对话的拼接格式如下：
player_name:q₁ <end>
agent_name:a₁ <end>
……
player_name:q_n <end>
agent_name:a_n <end>

计费项	接口返回参数
用户输入的字数	player_current_chars
角色输出的字数	agent_current_chars
角色记忆中的历史对话字数	history_chars

在这篇文章中：

角色模拟能力使用说明