1 整体介绍
在对话过程中，可以上传图片进行问答，也可以上传文档进行文件总结和内容提取。
图片问答：
文件问答：
说明：
随着产品能力的迭代，对文件类型，文件大小的限制会逐步放开，请参考智能体开发平台页面上的限制 。
文档问答需进行文档解析后，填充参数，使用 WebSocket 或者 HTTP SSE 进行对话 。
2 图片问答实现步骤
1. 调用 DescribeStorageCredential 接口，获取临时密钥。
2. 通过临时密钥，通过 COS 的SDK上传到 COS。
注意：
3. 填充参数 使用 WebSocket 或者 HTTP SSE 进行对话。
3.1 图片 COS 地址的拼接方法如下：
https:// +{DescribeStorageCredential.Response.Bucket} +"." +{DescribeStorageCredential.Response.Type} +"." +{DescribeStorageCredential.Response.Region} +".myqcloud.com" +{DescribeStorageCredential.Response.UploadPath}
如果发送图片，在此传递 markdown 格式的图片链接，例如
，请注意获取临时密钥的时候 IsPublic 字段。入参示例：
一张图片
{"request_id": "LHWObW2Sea-3173301679","session_id": "f5652b8c-e88e-4abc-8629-7952b741a433","bot_app_key":"xxxxxx","visitor_biz_id":"LHWObW2Sea","file_infos": [],"content": "描述下下面这张图片"}
多张图片
{"request_id": "LHWObW2Sea-317330dwe9","session_id": "f5652b8c-e88e-4111-8629-7952b741a433","bot_app_key":"xxxxxx","visitor_biz_id":"LHWObW2Sea","file_infos": [],"content": "描述下下面这张图片"}
3 文档问答实现步骤
在知识问答中，如果要上传文档进行实时问答，需要先对接实时文档解析接口。过程如下：
1. 调用DescribeStorageCredential 接口，获取临时密钥。
2. 通过临时密钥，通过 COS 的SDK上传到 COS。
注意：
3. 调用实时文档解析 docParse 接口，获取 doc_id。
4. 填充参数 使用 WebSocket 或者 HTTP SSE 进行对话。
3.1 实时文档解析
实时文档解析接口地址：
https://wss.lke.cloud.tencent.com/v1/qbot/chat/docParse请求方式：POST
3.1.1 请求参数
请放到 HTTP Body 中, 以 JSON 的形式发送，具体如下：
名称 | 类型 | 是否必填 | 说明 |
session_id | string(64) | 是 | 会话 ID，用于标识一个会话（外部系统提供，建议不同的用户端会话传入不同的session_id，否则同一个应用下的不同用户的消息记录会串掉） 参数长度：2-64个字符 校验规则： ^[a-zA-Z0-9_-]{2,64}$ ，一般可以用 uuid 来生成该值 uuid 示例：1b9c0b03-dc83-47ac-8394-b366e3ea67ef 注意： 文档解析的 session_id 要与会话的保持一致。如果一次多轮会话涉及多次上传文档，该 session_id 也要保持一致，会话时会校验。 |
bot_app_key | string(8) | 是 | 应用密钥（运营提供） |
request_id | string(255) | 是 | 请求的唯一 ID，建议使用 UUID 保证唯一性。 |
cos_bucket | string | 是 | cos 桶， 请从获取临时密钥接口返回中获取 |
file_type | string | 是 | 文件类型(txt|doc|docx|pdf|ppt|pptx)
示例值：txt|doc|docx|pdf|ppt|pptx |
file_name | string | 是 | 文件名 示例值：测试.docx |
cos_url | string | 是 | 平台 cos 路径，与 DescribeStorageCredential 接口查询 UploadPath 参数保持一致 示例值：/corp/1750375931926544384/1750376442139246592/doc/AaCIYEATBTYUQXDfXOTN-1807688648286535680.txt |
cos_hash | string | 是 | cos_hash x-cos-hash-crc64ecma 头部中的 CRC64 编码进行校验上传到云端的文件和本地文件的一致性；上传 cos 成功之后，从返回头中获取 |
e_tag | string | 是 | ETag 全称为 Entity Tag，是对象被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化， 上传 cos 成功之后， 从返回头中获取 示例值：\\"6886efe263f34c9f9401c2d910b02635\\" |
size | string | 是 | 上传文档的大小 注意： 请注意，该字段为 string 类型。 |
3.1.2 curl 调用示例
curl --location 'https://wss.lke.cloud.tencent.com/v1/qbot/chat/docParse' \\--header 'Content-Type: application/json' \\--data '{"session_id": "<your session_id>","request_id": "<random uuid>","cos_bucket": "lke-realtime-1251316161","file_type": "docx","file_name": "测试.docx","cos_url": "/corp/1750375931926544384/1750376442139246592/doc/AaCIYEATBTYUQXDfXOTN-1807688648286535680.txt","e_tag": "\\"6886efe263f34c9f9401c2d910b02635\\"","cos_hash": "6138891591882964610","size": "355","bot_app_key": "<your appkey>"}'
3.1.3 postman 调用示例
3.1.4 响应参数
SSE 流式返回
名称 | 类型 | 说明 |
session_id | string(64) | 会话 ID，同发起请求时的 session_id |
trace_id | string | 返回的唯一 ID |
is_final | bool | 消息是否已输出完成 |
doc_id | string | 文档解析接口返回的 doc_id |
process | int32 | 当前进度，整数，值为100时表示成功结束 |
status | string | 状态：PARSING、SUCCESS、FAILED |
timestamp | int64 | 时间戳，单位：秒 |
error_message | string | 错误信息，出错时返回 |
3.1.5 返回示例
{"type":"parsing","payload":{"doc_id":"0","error_message":"","is_final":false,"process":0,"session_id":"c7852s9d-aba8-4ee8-9c88-d65f28ddbc47","status":"PARSING","timestamp":1719821535,"trace_id":"1f1e5bfc9a3588d3abc62b9729fc6f62"},"message_id":"1b28b359-203e-4dbc-a103-6d92629cb1e0"}{"type":"parsing","payload":{"doc_id":"0","error_message":"","is_final":false,"process":2,"session_id":"c7852s9d-aba8-4ee8-9c88-d65f28ddbc47","status":"PARSING","timestamp":1719821535,"trace_id":"1f1e5bfc9a3588d3abc62b9729fc6f62"},"message_id":"60c2a29a-7658-4186-90a9-d81c8c0b14b4"}{"type":"parsing","payload":{"doc_id":"0","error_message":"","is_final":false,"process":85,"session_id":"c7852s9d-aba8-4ee8-9c88-d65f28ddbc47","status":"PARSING","timestamp":1719821536,"trace_id":"1f1e5bfc9a3588d3abc62b9729fc6f62"},"message_id":"65ca6da3-8909-42c4-9ea1-4a09be299a7b"}{"type":"parsing","payload":{"doc_id":"1807688654434383264","error_message":"","is_final":true,"process":100,"session_id":"c7852s9d-aba8-4ee8-9c88-d65f28ddbc47","status":"SUCCESS","timestamp":1719821536,"trace_id":"1f1e5bfc9a3588d3abc62b9729fc6f62"},"message_id":"43046854-c596-45f5-9195-3df4f82a67ff"}
3.2 文档对话参数示例
文件 COS 地址的获取方法如下：
标准模式下：
https:// +{DescribeStorageCredential.Response.Bucket} +"." +{DescribeStorageCredential.Response.Type} +"." +{DescribeStorageCredential.Response.Region} +".myqcloud.com" +{DescribeStorageCredential.Response.UploadPath}
Multi-Agent 模式下：
1. 调用DescribeStorageCredential接口获取临时Token、临时 SecretId和临时 SecretKey。
2. 调用预签名 URL接口获取临时访问 COS 地址。
示例
不带 content 的实时文档：
{"payload": {"request_id": "LkfnMf5IrS-4486169698","session_id": "c60f0463-0176-4c15-a236-e4cbb6c21f97","file_infos": [{"doc_id": "1833044072669409152","file_name": "河边的美景","file_type": "docx","file_size": "34859","file_url": "https://lke-realtime-1251316161.cos.ap-guangzhou.myqcloud.com/corp/1753030485940633600/1781229014471147520/doc/xxxxxxx.docx"}],"content": ""}}
带 content 的实时文档：
{"payload": {"request_id": "XCBLyiWwYV-9639940128","session_id": "c60f0463-0176-4c15-a236-e4cbb6c21f97","file_infos": [{"doc_id": "1833044598014003968","file_name": "河边的美景","file_type": "docx","file_size": "34859","file_url": "https://lke-realtime-1251316161.cos.ap-guangzhou.myqcloud.com/corp/1753030485940633600/1781229014471147520/doc/xxxxxxdocx"}],"content": "提取文档中的主要观点"}}
3.3 特别说明
文档解析完成后，需要组装成 WebSocket 或者 HTTP SSE 对话时的 file_infos 字段，然后调用对话即可使用， 下面是几个简单 file_infos 字段示例。
注意：
1. doc_id 和 file_size 是字符串类型，如果传入整数类型会报参数错误。
2. file_name 不要加文件后缀。
3. 对话时候的 session_id 请和调用 docParse 接口传入的 session_id 保持一致， 否则会导致检索不到传入的文件。
4. 实时文档解析上传的文档有会话轮次限制，会话轮次同页面配置的上下文轮次保持一致，默认时效性是24h，如果24h 内有基于该文档的新对话，则续期24h，请勿反复使用同一个文档 id 问答。
4 图片问答，文档问答 Demo
说明：
其他编程语言暂无 Demo，可以参考文档和现有 Demo 自行实现。
Demo 的目的为快速验证， 使用的是 HTTP SSE 的对话方式，用户可结合实际业务需求，选择 Websocket 对话方式。
