语义检索与语音识别

18.1 POST /v1/api/semantic_nav/semantic_search

字段	类型	必填	说明
prompt	string	是	去除前后空白后非空的自然语言描述
map_name	string	否	建议指定地图，限定语义集合

{"prompt":"找到靠近窗户的会议桌","map_name":"office_1f"}

响应 data 为匹配结果数组。每个结果将向量库 payload 的字段展开到结果顶层，再增加 image 和 score；不是固定的 {payload:{...}} 结构。

[{"scene":"会议桌旁","image_file_path":"/semantic/images/example.jpg","score":0.91,"image":"base64-image-bytes"}]

scene 等是业务 payload 示例，不是所有设备必有字段；image 为 base64 图像，score 为相似度 number。没有结果可为空数组。接口只检索位置，不自动导航；客户端须解析实际位姿、确认目标后再调用 Missions。依赖 LLM/T2V/向量库；主要调用失败为 502/1005，部分检索步骤会降级为空结果。

18.2 POST /v1/api/semantic_nav/vecdb_items

字段	类型	默认 / 说明
page	integer	从 1 开始，<1 按 1
page_size	integer	<1 按 20；建议控制为小页，当前未统一设定最大值
map_name	string	可选，建议指定
with_vector	boolean	默认 false，true 才返回向量

{"page":1,"page_size":20,"map_name":"office_1f","with_vector":false}

{"points":[{"id":"point-example-id","payload":{"image_file_path":"/semantic/images/example.jpg"}}],"end":true,"next_offset":null}

points 每项有 id（向量库原始类型）、payload（object），请求 with_vector=true 时有 vector。end 为 boolean，next_offset 为下游游标或 null。当前请求不接收 next_offset，按 page 查询；服务端滚动到指定页，大页码成本更高。集合不存在时返回空 points、end=true。

18.3 POST /v1/api/semantic_nav/map_summaries

请求 map_names:string[] 必填，1–100 项：

{"map_names":["office_1f","office_2f"]}

响应 data：

{"summaries":{"office_1f":{"state":"available","point_count":120,"collection_name":"collection-from-device","storage_mode":"dedicated"},"office_2f":{"state":"empty","point_count":0,"storage_mode":"legacy"}}}

state 为 available/empty/unknown；point_count 可省略，unknown 不应解释为 0。reason 为可选诊断，collection_name 为可选集合名；storage_mode 为 dedicated 或 legacy。单张地图查询失败不使整批失败。空名称项会被跳过，客户端应先清洗名称。

18.4 POST /v1/api/semantic_nav/get_image_of_point

两种引用方式：

{"image_path":"/semantic/images/example.jpg"}

或：

{"image_id":"12345","camera_name":"front"}

三个字段均为 string；优先 image_path，否则 image_id 与 camera_name 必须成对提供。使用向量点返回的合法引用，不自行猜测路径。成功 data={"image":"base64-image-bytes"}，没有 data URI 前缀。JSON 非法为 400/1001；缺少有效引用、文件读取失败等在当前单图入口映射为 502/1005，不能只按 404 处理。

18.5 POST /v1/api/semantic_nav/images/batch

{"items":[{"key":"front-12345","image_id":"12345","camera_name":"front"},{"key":"other-image","image_path":"/semantic/images/other.jpg"}]}

items 非空，每项 key:string 必填，并提供 image_path 或 image_id+camera_name。最多 20 个不同 key；重复 key 合并，采用首个引用。响应：

{"items":[{"key":"front-12345","status":"available","image":"base64-image-bytes","mime_type":"image/jpeg"},{"key":"other-image","status":"missing"}]}

status 为 available/missing/unavailable；image、mime_type 仅成功时出现。单图缺失不影响其他项；请求结构非法为 400/1001，整批上下文或服务调用失败可为 502/1005。

18.6 POST /v1/api/interact/asr

上传音频后返回 SSE 语音识别流，遵循 2.3 的业务认证规则。

字段	位置	类型	必填 / 默认
audio	multipart	file	必填，非空；推荐 16-bit PCM 单声道 WAV
language	query	string	默认 zh
enable_itn	query	boolean 文本	默认 false；当前无法解析的值也回退 false，建议明确传 true/false

curl -N -sS -H "Authorization: Bearer $ORSUS_TOKEN" \
  -F 'audio=@speech.wav' \
  "$ORSUS_ORIGIN/v1/api/interact/asr?language=zh&enable_itn=true"

成功 Content-Type 为 text/event-stream，上游流原样转发，按实际 chunk 的 choices[0].delta.content 累积识别文本。示意：

data: {"choices":[{"delta":{"content":"前往"}}]}

data: {"choices":[{"delta":{"content":"会议室"}}]}

data: [DONE]

不能把一次 TCP 读取当成一条完整 SSE，也不要把 [DONE] 送给 JSON.parse。鉴权或上传阶段失败仍为普通 JSON 错误；流已经开始后中断不保证能改写为 JSON 信封。

缺少/空 audio：400/1001；DashScope API Key 未配置或请求构造失败：500/1003；上游不可达/报错：502/1005。API Key 保留在服务器。当前 handler 以 WAV data URL 转发上传内容，不能仅改文件扩展名就保证其他音频格式可识别。