Skip to main content

对话 API

意图可以通过文本被识别并使用对话集成触发。

一个 API 端点可用于接收输入句子并生成对话响应。通过传递 Home Assistant 生成的对话 ID，可以在多个输入和响应之间跟踪一个“对话”。

该 API 可通过 REST API 和 WebSocket API 访问。

一个句子可以通过 POST 到 /api/conversation/process，例如：

{
  "text": "打开客厅的灯",
  "language": "zh"
}

或者通过 WebSocket API 发送，例如：

{
  "type": "conversation/process",
  "text": "打开客厅的灯",
  "language": "zh"
}

以下输入字段可用：

名称类型描述
text字符串输入句子。
language字符串可选。输入句子的语言（默认为配置的语言）。
agent_id字符串可选。处理请求的对话代理（默认为 home_assistant）。
conversation_id字符串可选。唯一 ID，用于跟踪对话。由 Home Assistant 生成。

对话响应​

从 /api/conversation/process 返回的 JSON 响应包含触发意图的效果的信息，例如：

{
  "continue_conversation": true,
  "response": {
    "response_type": "action_done",
    "language": "zh",
    "data": {
      "targets": [
        {
          "type": "area",
          "name": "客厅",
          "id": "living_room"
        },
        {
          "type": "domain",
          "name": "灯光",
          "id": "light"
        }
      ],
      "success": [
        {
          "type": "entity",
          "name": "我的灯",
          "id": "light.my_light"
        }
      ],
      "failed": []
    },
    "speech": {
      "plain": {
        "speech": "已打开客厅的灯"
      }
    }
  },
  "conversation_id": "<generated-id-from-ha>"
}

在 "response" 对象中可用的属性：

名称类型描述
response_type字符串可能为 action_done、query_answer 或 error（参见响应类型）。
data字典每种响应类型的相关数据。
language字符串意图和响应的语言。
speech字典可选。要对用户说的响应文本（参见语音）。

对话 ID与对话响应一起返回。

如果 continue_conversation 设置为 true，对话代理会期望用户的后续输入。

响应类型​

动作完成​

意图在 Home Assistant 中产生了一项行动，例如打开灯。响应的 data 属性包含一个 targets 列表，其中每个目标如下所示：

名称类型描述
type字符串目标类型。可能为 area、domain、device_class、device、entity 或 custom。
name字符串受影响目标的名称。
id字符串可选。目标的 ID。

还包含两个附加目标列表，包含成功或失败的设备或实体：

{
  "response": {
    "response_type": "action_done",
    "data": {
      "targets": [
        (area 或 domain)
      ],
      "success": [
        (成功的实体/设备)
      ],
      "failed": [
        (失败的实体/设备)
      ]
    }
  }
}

一个意图可以有多个目标，这些目标按顺序应用。目标必须从一般到具体地排序：

  • area
  • domain
    • Home Assistant 集成域，例如“light”
  • device_class
    • 域的设备类别，例如“cover”域的“garage_door”
  • device
  • entity
  • custom
    • 一个自定义目标

大多数意图最终有 0、1 或 2 个目标。当前只有在涉及设备类时才会发生 3 个目标。目标组合的示例：

  • “关闭所有灯”
    • 1 个目标: domain:light
  • “打开厨房的灯”
    • 2 个目标: area:kitchen, domain:light
  • “打开厨房的窗帘”
    • 3 个目标: area:kitchen, domain:cover, device_class:blind

查询回答​

响应是对问题的回答，例如“温度是多少？”参见语音属性以获取答案文本。

{
  "response": {
    "response_type": "query_answer",
    "language": "zh",
    "speech": {
      "plain": {
        "speech": "温度是 65 度"
      }
    },
    "data": {
      "targets": [
        {
          "type": "domain",
          "name": "气候",
          "id": "climate"
        }
      ],
      "success": [
        {
          "type": "entity",
          "name": "Ecobee",
          "id": "climate.ecobee"
        }
      ],
      "failed": []
    }
  },
  "conversation_id": "<generated-id-from-ha>"
}

错误​

在意图识别或处理期间发生了错误。请参见 data.code 以获取特定类型错误，以及语音属性以获取错误信息。

{
  "response": {
    "response_type": "error",
    "language": "zh",
    "data": {
      "code": "no_intent_match"
    },
    "speech": {
      "plain": {
        "speech": "对不起，我听不懂"
      }
    }
  }
}

data.code 是一个字符串，可以是以下之一：

  • no_intent_match - 输入文本未匹配任何意图。
  • no_valid_targets - 目标区域、设备或实体不存在。
  • failed_to_handle - 处理意图时发生了意外错误。
  • unknown - 在意图处理范围之外发生了错误。

语音​

对用户的口头响应存储在响应的 speech 属性中。可以是普通文本（默认）或SSML。

对于普通文本语音，响应看起来像：

{
  "response": {
    "response_type": "...",
    "speech": {
      "plain": {
        "speech": "...",
        "extra_data": null
      }
    }
  },
  "conversation_id": "<generated-id-from-ha>"
}

如果语音是SSML，则看起来如下所示：

{
  "response": {
    "response_type": "...",
    "speech": {
      "ssml": {
        "speech": "...",
        "extra_data": null
      }
    }
  },
  "conversation_id": "<generated-id-from-ha>"
}

对话 ID​

如果回答的对话代理支持，则可以根据 Home Assistant 内部生成的唯一 ID 跟踪对话。要继续对话，请从 HTTP API 响应中检索 conversation_id（与对话响应一起）并将其添加到下一个输入句子中：

初始输入句子：

{
  "text": "初始输入句子。"
}

JSON 响应包含对话 ID：

{
  "conversation_id": "<generated-id-from-ha>",
  "response": {
    (对话响应)
  }
}

使用下一个输入句子进行 POST：

{
  "text": "相关输入句子。",
  "conversation_id": "<generated-id-from-ha>"
}

预加载句子​

可以使用 WebSocket API 预加载某种语言的句子：

{
  "type": "conversation/prepare",
  "language": "zh"
}

以下输入字段可用：

名称类型描述
language字符串可选。要加载的句子的语言（默认为配置的语言）。