操作 API

本页介绍了操作 API 以及如何使用它。

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

简介

如果对话能够驱动角色的行为，并赋予其操控环境的能力，那么对话会变得更加吸引人。Action API 通过允许你定义角色可以执行的各种动作来实现这一点。这些动作通常与环境中可用的物体相关联。

要充分使用 Action API，必须先理解几件事情，才能把它的作用发挥到最大。这里我们解释一些应指导如何编写这些内容的原则。

本教程将使用代码示例和注释来展示如何有效使用 Action API。

设置

为了顺利跟随本教程，需要先完成以下准备工作。创建一个 Colab 笔记本即可，无需安装任何软件包也能继续。

# 导入几个库
import base64
import json
import requests

# 在这里使用你的角色 ID
CHAR_ID = "<你的角色 ID>"

# 你应该在这里设置你的 Convai API 密钥
CONVAI_KEY = "<你的 Convai API 密钥>"

# 这是将生成动作和响应的 URL
action_url = "https://api.convai.com/character/getResponse"

# 用于更新背景故事的 URL
url = "https://api.convai.com/character/update"

Action API 的组成部分

在环境中生成动作所需的基本构成如下。

1. Actions
2. 对象
3. 角色
4. 背景故事

现在让我们详细讨论这些内容。我们在这里把它们列出来，但在进行设置时，你应该回到每个部分分别查看。

对象

与动作一样，关于物体还有一些细节是用户应该注意的。如果有多个相似的物体，最好给它们编号。例如，不要写“5 把椅子”，而应写成“椅子#1”“椅子#2”等。如果你需要角色为你带来某个特定物体，也应该明确提出，例如“给我拿 3 号椅子”。你还可以提到能够与该物体交互的动作，以提高效果。

下面我们给出两个示例，说明如何定义物体以及如何最好地进行定义。

## 基本定义
# 定义动作最简单的方法如下，使用 convert()
# 函数，我们可以直接将其转换为 API 所需的形式， 
# API 参考将说明如何进行 API 调用。

# objects = [{"name": "莫吉托","description": "难得一次，是一杯无酒精的莫吉托。"},
#            {"name": "特基拉日出","description": "不是我个人最喜欢的。"},
#            {"name": "白俄罗斯","description": "那个家伙最喜欢的饮品。"},
#            {"name": "点唱机","description": "一台有很多歌曲的点唱机。"},
#            {"name": "新鲜切片橙子","description": "一些清爽带劲的橙子，让你精神一振。"},
#            {"name": "炸鱼薯条","description": "经典的炸鱼薯条。"},
#            {"name": "一些萨莫萨","description": "一种美味的印度小吃。"},
#            {"name": "书","description": "一本让你在享用餐点时打发时间的书。"},
#            ]

## 高级（更好的）定义
# 定义物体的更好方法是，在名称中也指定可以在其上执行哪些动作 
#。请记住，切勿在“name”或 
# “description”字段中使用 ;，因为它们会在 API 调用中被用作分隔符，并且
# 可能会导致不稳定的行为。
#
# 虽然这样定义物体可能更困难，但根据我们的经验 
# 它能大幅提升性能。"播放、提供、给予、叫出租车"
objects = [{"name": "莫吉托（可以：提供|不可以：播放、给予）","description": "难得一次，是一杯无酒精的莫吉托。"},
           {"name": "特基拉日出（可以：提供|不可以：播放、给予）","description": "不是我个人最喜欢的。"},
           {"name": "白俄罗斯（可以：提供|不可以：播放、给予）","description": "那个家伙最喜欢的饮品。"},
           {"name": "点唱机（可以：播放|不可以：提供、给予）","description": "一台有很多歌曲的点唱机。"},
           {"name": "新鲜切片橙子（可以：提供|不可以：播放、给予）","description": "一些清爽带劲的橙子，让你精神一振。"},
           {"name": "炸鱼薯条（可以：提供|不可以：播放、给予）","description": "经典的炸鱼薯条。"},
           {"name": "一些萨莫萨（可以：提供|不可以：播放、给予）","description": "一种美味的印度小吃。"},
           {"name": "书（可以：给予|不可以：播放、提供）","description": "一本让你在享用餐点时打发时间的书。"},
           ]

背景故事

重要的是要知道，背景故事也会影响 Action API 的表现。要有效生成动作，最重要的一点是在背景故事本身中加入一些关于物体、角色和动作的信息。（你也可以使用知识库来放入这些信息，但我们建议改用背景故事来完成）这里我们将给出一个示例。你可以看到我们如何说明场景中有哪些物体，以及关于它们的一些信息。如果可以的话，最好也在这里指定一些有关环境的信息。

关于角色本身的任何信息都可以放在知识库中。

backstory = """一个酒保角色，能够帮助执行不同任务。 

它可以提供几种饮品：
1. 莫吉托
2. 特基拉日出
3. 白俄罗斯

它周围还有一些物体；这些是：
1. 点唱机
2. 一碗花生
3. 新鲜切片橙子
4. 炸鱼薯条
5. 一些萨莫萨
6. 书

上述物体中，这个角色可以执行若干动作。 
角色可以同意或拒绝执行用户要求的任务。 
同样，如果被要求对其他物体做某件事，角色只有在 
可用的动作能够作用于可用物体时才能做到。角色在请求时还可以执行叫出租车
动作。"""

# 顺带一提，我们也提供了更新背景故事的代码，以防你想
# 修改内容并亲自尝试。
payload = json.dumps({
  "charID": CHAR_ID,
  "backstory": backstory,
})
headers = {
  'CONVAI-API-KEY': CONVAI_KEY,
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Actions

Action 是此 API 的核心。要创建有效的动作，你需要确保这些动作能够普遍适用且简单。尽量不要把动作设得过于具体。例如，名为“Show”的动作会比“Demonstrate”更有效。同样，“Walks To”或“Runs To”也不如“Moves To”或“Go To”有效，因为后一组在某种意义上比前一组更“通用”。

在定义动作时，你还应保持大小写一致。如果你使用小写，那么所有动作都应写成小写，依此类推。为了获得最佳效果，这些动作还必须符合角色背景的语境。

动作可以通过 API 调用发送，也可以在 Playground UI 中设置。这里我们演示 API 调用版本。如果你想使用 UI 设置它们，请前往 https://convai.com/pipeline/dashboard/character 并点击 Actions 按钮添加你的动作，最后点击 Update 按钮。

actions = "播放、提供、给予、叫出租车"

角色

这很简单，只需提供场景中存在的角色即可。你可以添加两个以上的角色；例如，如果你在一家餐厅里和多人在一起，可以把他们都加在这里。

你应确保把角色的重要信息放在知识库或背景故事中。不要把任何真正重要的信息写在 bio 里。

characters = [{"name": "用户", "bio": "这是使用 Action API 的人。"},
              {"name": "Action-API-Doc-Bot", "bio": "在这里帮助编写 Convai 文档。"},]

API 参考

现在我们可以通过 API 参考，以及调用 Action API 的各种方式来结束本教程。

userText = input("输入你的命令：")

payload={'userText': userText,
  'charID': CHAR_ID,
  'sessionID': '-1',
  'voiceResponse': 'false',
  'actions': actions,
  'classification':'multistep', 
  'objects': json.dumps(objects),
  'characters': json.dumps(characters),
  }

files = []

headers = {
  'CONVAI-API-KEY': CONVAI_KEY 
}

response = requests.request("POST", action_url, headers=headers, data=payload, files=files)

response = json.loads(response.text)

print(json.dumps(response, indent=4))

# 响应体
# {
#     "userQuery": "你能给我一杯饮料吗？",
#     "charID": "17e9cbde-abcd-11ed-9d60-42010a80000d",
#     "sessionID": "4ba18da3db1627953bf04f3a4021779f",
#     "text": "当然！你想要什么？我这里有莫吉托、特基拉日出和白俄罗斯可供选择。",
#     "response": "当然！你想要什么？我这里有莫吉托、特基拉日出和白俄罗斯可供选择。",
#     "actionSequence": " \n提供 莫吉托\n 提供 特基拉日出\n 提供 白俄罗斯"
# }