大模型对话

更新时间：2024-10-10

在线调试

百度智能云千帆提供了 API在线调试平台-示例代码，用于帮助开发者调试接口，平台集成快速检索、查看开发文档、查看在线调用的请求内容和返回结果、复制和下载示例代码等功能，简单易用。

接口描述

该接口用于在一轮对话中向大模型发送消息。

权限说明

Authorization需要填写密钥。

接口定义

URL	/v2/app/conversation/runs
Method	POST
Content-Type	application/json
Authorization	请求签名(此签名为应用工作台密钥)

请求结构

POST /v2/app/conversation/runs HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json

{
    "app_id": "85036d8f-239c-469c-b342-b62ca9d696f6",
    "query": "根据文件中的数据，统计这几所学校小学生有多少",
    "stream": true,
    "conversation_id": "355a4f4e-a6d8-4dec-b840-7075030c6d22",
    "file_ids": [
        "cdd1e194-cfb7-4173-a154-795fae8535d9"
    ]
}

请求头域

除公共头域外，无其它特殊头域。

请求参数

字段	类型	必填	说明
app_id	string	是	app_id，来源于个人空间-应用-应用ID。
end_user_id	string	否	终端用户ID，限制6 - 64字符
query	string	是	用户query文字，长度限制2000字符。
stream	bool	是	是否以流式接口的形式返回数据，默认false。
conversation_id	string	是	对话id，可通过新建会话接口创建。
file_ids	list[string]	否	如果在对话中上传了文件，可以将文件id放入该字段，目前只处理第一个文件。
tool_choice	object	否	控制大模型使用组件的方式
tools	list[Tool]	否	一个列表，其中每个字典对应一个工具
tool_outputs	list[ToolOutput]	否	内容为本地工具执行的结果

tool_choice对象

字段	类型	必填	说明
type	string	是	auto/function，auto表示由LLM自动判断调什么组件；function表示由用户指定调用哪个组件，仅支持强制命中通过工作流自定义的组件，官方组件不支持强制命中；如果想获取组件的原始输出，请在应用回复设置中将该组件设置成回复节点，详细操作可参考调用示例
function	object	否	组件对象，包括组件的英文名称和入参

tool_choice.function对象

字段	类型	必然存在	说明
name	string	是	组件的英文名称（唯一标识），用户通过工作流完成自定义组件后，可在个人空间-组件下查看组件英文名称
input	object	是	当组件没有入参时填入空对象{}

Tool对象

字段	类型	必然存在	说明
type	string	是	枚举： function: 支持fucntion call模式调用工具
function	object	是	工具对象

Tool.function对象

字段	类型	必然存在	说明
name	string	是	函数名只允许数字、大小写字母和中划线和下划线，最大长度为64个字符。一次运行中唯一。
description	string	是	函数描述
parameters	object	是	函数请求参数，JSON Schema 格式，参考JSON Schema描述在此基础上，新增约束如下： 1. 当某一字段为object类型时，properties字段必选，properties内可为空。 2. 当某一字段为array类型时，items字段必选，items内可为空。

ToolOutput对象

字段	类型	必然存在	说明
tool_call_id	string	是	工具调用的ID。来源于上一轮Run请求时，Interrupt状态时，tool_calls \ id字段
output	string	是	function call工具的输出。如果是json，也需要对json序列化成string

响应头域

除公共头域外，无其它特殊头域。

响应参数

字段	类型	必然存在	说明
request_id	string	是	request_id便于追踪。
date	string	是	消息返回时间的时间戳 UTC时间格式。
answer	string	是	文字答案。流式场景下是增量数据。
conversation_id	string	是	对话id，可以用于后续调用，有效期为7天。
message_id	string	是	消息id, 流式场景下多次推流message_id保持一致。
is_completion	boolean	是	流式消息推送回答结果是否完结。
content	list[dict]	是	节点输出信息相关内容。具体见下文content字段定义。

content字段

字段	类型	必然存在	说明
event_code	int	是	事件错误码事件状态正常。事件状出错时，推送非0值，只代表事件状态，不代表整次对话状态。
event_message	string	是	事件执行错误提示信息。
event_type	enum	是	事件类型 rag: 知识问答 function_call: function_call 工具 ChatAgent: 闲聊、总结、数字人口播文本 Workflow: 自定义工作流组件其它工具: TTS、GetWeather、QueryArxiv、CodeInterpreter、WebPilot、WolframAlpha。全部列表可见事件类型说明部分。
event_id	string	是	事件id。
event_status	enum	是	事件执行状态: preparing：准备中 running：运行中 error：错误 done：执行完成 interrupt：中断，等待用户提交 tool call结果
content_type	enum	是	事件本次输出内容的类型。 status 状态事件，无数据输出 text 文本回答 image 图片 files 文件 function_call: function_call image: 图片url地址 audio：语音url地址 video：视频url地址 oral_text：数字人口播文本
outputs	object	是	每个事件个性化输出内容的汇总字段，根据事件的类型不同， outputs下内容不同。
usage	object	是	模型用量仅Chat Agent和Function Call有，按照各个独立的event_type计数。
tool_calls	list[ToolCall]	否	tool_calls: 需要用户本地调用的tool，包含了调用所需的参数和上下文

usage 模型用量对象

字段名称	类型	必然存在	说明
prompt_tokens	int	是	输入token数
completion_tokens	int	是	输出token数
total_tokens	int	是	总token数
name	string	是	消耗tokens的模型名称

ToolCall对象

字段名称	类型	必然存在	说明
id	string	是	工具调用的ID。当您在提交工具输出时，必须引用此ID。
type	string	是	需要输出的工具调用的类型。就目前而言，这始终是function。
function	object	是	函数定义。
function \ name	string	是	函数的名称
function \ arguments	string	是	模型希望您传递给函数的参数，需要是一个json dump string

outputs字段

说明: 每个事件类型的outputs字段均不相同。

字段名称	类型	描述
outputs	Object	event_type 为 rag , 结果包括以下字段: text: string 普通文本 references list[object] 包含reference对象的数组， reference格式在下面定义 event_type 为 function_call , 结果包括以下字段: text: string 普通文本。function_call 的描述json event_type 为 Workflow，结果包括以下字段： text: string 普通文本 meta：json 自定义组件的描述信息 event_type 为其它组件名，可能会出现以下多种字段 urls: 外部链接 files: 工具生成的文件链接 image：工具生成的图片url audio：工具生成的语音url video：工具生成的视频url
-- text	string	各个事件都可能产生文字信息
-- meta	json	自定义组件信息
-- references	list[object]	通用类型 Reference的列表
-- urls	list[string]	工具生成的文件链接列表
-- files	list[string]	工具生成的可下载文件地址列表
-- image	string	工具生成的图片url
-- audio	string	工具生成的语音url
-- video	string	工具生成的视频url

reference参考信息

定义: 问答结果中的引用参考。如大模型的回答引用了某切片，需要在问答结果中标注出答案的来源位置。

字段	类型	必然存在	说明
id	String	是	这个id对应content信息的id
from	String	是	信息来源
url	String	否	BaiduSearch 的专用字段
content	String	是	文字描述通用字段，一般用来当做文档名或者链接的title使用
segment_id	String	否	切片id 知识问答专有字段
document_id	String	否	文档id 知识问答专有字段
dataset_id	String	否	数据集id 知识问答专有字段
knowledge_base_id	String	否	知识库id 知识问答专有字段
document_name	String	否	文档名字知识问答专有字段

function_call描述json

字段	类型	必然存在	说明
arguments	String	是	参数
component_code	String	是	组件编码
component_name	String	是	组件名称

meta自定义组件描述json

字段	类型	必然存在	说明
workflow_id	String	是	组件id
workflow_code	String	是	组件编码
workflow_name	String	是	组件名称
desc	String	是	组件描述

事件类型说明

事件编码	事件名称
rag	知识问答
function_call	function_call 工具
ChatAgent	闲聊、总结、数字人口播文本
Workflow	自定义工作流组件
SimilarQuestion	相似问生成
WeatherQuery	天气查询
QueryExpressPackage	快递查询
QueryFlights	航班动态查询
DocumentUnderstanding	长文档内容理解
Translation	文本翻译-通用版
TableOCR	表格文字识别
PlantRecognition	植物识别
ImageUnderstand	图像内容理解
HandwriteOCR	手写文字识别
QRcodeOCR	二维码识别
VideoGet	热门视频
CodeInterpreter	代码解释器
Arxiv	论文搜索
WebPilot	浏览网页
NewsGet	头条新闻
TTS	短文本在线合成
WolframAlpha	Wolfram Alpha
BingImageSearch	必应图片搜索
ZhouGongDreamInterpreter	周公解梦大师
HealthAssistant	健康小助手
AnimalRecognition	动物识别
ObjectRecognition	通用物体和场景识别-高级版
GeneralOCR	通用文字识别-高精度版
LotteryResult	彩票开奖结果
DocFormatConverter	文档格式转换
ASR	短语音识别-极速版
Text2Image	文生图
ECommerceProductInquiryTB	电商商品查询-tb
BaiduSearch	百度搜索
ECommerceProductInquiryJD	电商商品查询-jd
DocCropEnhance	文档矫正增强
WebSummary	网页内容总结
SportsEventInformation	体育赛事信息
BaiduNovel	百度小说
Excel2Figure	Excel转图表
MixCardOCR	身份证混贴识别
StyleRewrite	风格转写
StyleWriting	风格写作
ExchangeRateCalc	汇率计算
FundExpert	基金专家
MovieAssistant	电影助手
TravelExpert	旅游达人
ImageAssistant	搜图助手
ExamAssistant	高考助手
StockGuru	股票大师
ArticleAssistant	文库助手
RoutePlanning	百度地图路线规划
QueryRewrite	多轮改写
Nl2pandas	自然语言转pandas
TagExtraction	标签抽取
DialogSummary	会话小结
OralQueryGeneration	口语化Query生成
QueryDecomposition	复杂Query分解
IsComplexQuery	复杂Query判定
QAPairMining	问答对挖掘
MRC	阅读理解问答
Playground	空应用
SelectTable	GBI选表
NL2Sql	GBI问表
DishRecognition	菜品识别
LandmarkRecognition	地标识别
DocParser	文档解析
DocSplitter	文档切分
Matching	语义匹配
Embedding	向量计算
HandwriteOCR	手写体OCR识别
ExtractTableFromDoc	表格抽取
BESRetriever	向量检索-BES
BaiduVDBRetriever	向量检索-VDB
HallucinationDetection	幻觉检测
MusicAssistant	音乐助手
HotDramaAssistant	热剧助手
CardInfoExtractor	卡证信息抽取

请求curl示例

curl --location 'https://qianfan.baidubce.com/v2/app/conversation/runs' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data '{
    "app_id": "85036d8f-239c-469c-b342-b62ca9d696f6",
    "query": "根据文件中的数据，统计这几所学校小学生有多少",
    "stream": true,
    "conversation_id": "355a4f4e-a6d8-4dec-b840-7075030c6d22",
    "file_ids": [
        "cdd1e194-cfb7-4173-a154-795fae8535d9"
    ]
}'

正确响应示例

HTTP/1.1 200 OK

// 一条 function_call事件类型的流式消息
{
    "request_id": "a335502e-502d-426d-9e87-ea8ad47efc8d",
    "date": "2024-04-26T09:11:13Z",
    "answer": "",
    "conversation_id": "1fdc9182-de2d-4c56-bf64-a72d98c2b59f",
    "message_id": "66c1c8c5-d04a-4376-91ff-3a7285e698f0",
    "is_completion": false,
    "content": [
        {
            "event_code": 0,
            "event_message": "",
            "event_type": "function_call",
            "event_id": "6",
            "event_status": "done",
            "content_type": "function_call",
            "outputs": {
                "text": {
                    "arguments": {
                        "query": "对'北京小学.xlsx'文件中的'count'列数据进行求和操作",
                        "upload_file": "北京小学.xlsx"
                    },
                    "component_code": "CodeInterpreter",
                    "component_name": "代码解释器"
                }
            },
            "usage": {
                    "prompt_tokens": 3476,
                    "completion_tokens": 0,
                    "total_tokens": 3476,
                    "name": "ERNIE-4.0-8K"
            }
        }
    ]
}


// 一条 ChatAgent 事件类型的流式消息
{
    "request_id": "a335502e-502d-426d-9e87-ea8ad47efc8d",
    "date": "2024-04-26T09:11:59Z",
    "answer": "北京小学.xlsx'文件中的数据，这几所学校小学生的总数为：430人。",
    "conversation_id": "1fdc9182-de2d-4c56-bf64-a72d98c2b59f",
    "message_id": "66c1c8c5-d04a-4376-91ff-3a7285e698f0",
    "is_completion": false,
    "content": [
        {
            "event_code": 0,
            "event_message": "",
            "event_type": "ChatAgent",
            "event_id": "13",
            "event_status": "running",
            "content_type": "text",
            "outputs": {
                "text": "北京小学.xlsx'文件中的数据，这几所学校小学生的总数为：430人。"
            }
        }
    ]
}


// 成功开启流式消息后，有出现异常需要终止流，返回的异常消息

{
  "request_id": "ae2225f7-1c2e-427a-a1ad-5413b762957d",
  "code": "ChatError",
  "message": "流式消息发生异常"
}

错误响应示例

HTTP/1.1 401 OK

{
  "request_id": "ae2225f7-1c2e-427a-a1ad-5413b762957d",
  "code": "PermissionDeniedError",
  "message": "没有权限"
}

其他示例

1. 强制执行组件

curl --location --request POST 'https://qianfan.baidubce.com/v2/app/conversation/runs' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data-raw '{

    "app_id": "b412f6b3-d9e9-4617-8be5-94df02b06bdf",
    "query": "你好",
    "stream": true,
    "conversation_id": "377208a9-2ec2-4ed3-bc1f-120d20d0018c",
    "tool_choice": {
        "type": "function",
        "function": {
            "name": "QueryFlights",
            "input": {
                "flight_number":"CZ8889"
            }
        }
    }
}'

HTTP/1.1 200 OK

// 一条 组件响应结果的流式消息
{
    "request_id": "55d1825e-a3f6-4267-ae12-8061562f45f9",
    "date": "2024-08-14T16:20:08Z",
    "answer": "",
    "conversation_id": "377208a9-2ec2-4ed3-bc1f-120d20d0018c",
    "message_id": "9d637244-65e3-4b96-9f15-fe4ff69d5e15",
    "is_completion": false,
    "content": [
        {
            "result_type": "",
            "event_code": 0,
            "event_message": "",
            "event_type": "QueryFlights",
            "event_id": "2",
            "event_status": "done",
            "content_type": "text",
            "visible_scope": "",
            "outputs": {
                "text": "[\n    {\n        \"航班号\": \"CZ8889\",\n        \"是否延误\": null,\n        \"是否改道\": null,\n        \"是否取消\": null,\n        \"始发地\": \"Beijing\",\n        \"目的地\": \"上海 上海浦东 CN\",\n        \"当前状态\": \"已到达 / 到达停机位\",\n        \"预估出发时间\": \"2024-08-14T04:28:00Z\",\n        \"实际出发时间\": \"2024-08-14T04:24:00Z\",\n        \"预估到达时间\": \"2024-08-14T06:17:00Z\",\n        \"实际到达间\": null\n    }\n]"
            }
        }
    ]
}

Tips：如果想获取组件的原始输出，请在应用回复设置中将该组件设置成回复节点

2. Function call本地函数

curl --location --request POST 'https://qianfan.baidubce.com/v2/app/conversation/runs' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "4d4b1b27-d607-4d2a-9002-206134217a9f",
    "query": "今天北京的天气怎么样",
    "stream": true,
    "conversation_id": "8c5928f7-a9e7-4826-a027-3eb1f97f6eab",
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "仅支持中国城市的天气查询，参数location为中国城市名称，其他国家城市不支持天气查询",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. Beijing"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "celsius",
                                "fahrenheit"
                            ]
                        }
                    },
                    "required": [
                        "location",
                        "unit"
                    ]
                }
            }
        }
    ]
}'

HTTP/1.1 200 OK

// 一条 中断响应结果的流式消息
{
    "code": 0,
    "message": "",
    "trace_id": "2f7b17ea-b526-4dec-946c-aef99d279c5b",
    "time": 1723622172917,
    "result": {
        "answer": "",
        "conversation_id": "c01171ba-e33f-4da3-aae1-b259c88e2140",
        "message_id": "db4873e9-c30d-4721-8857-6856a0a28824",
        "is_completion": false,
        "content": [
            {
                "result_type": "",
                "event_code": 0,
                "event_message": "",
                "node_name": "root",
                "dependency_nodes": [

                ],
                "event_type": "Interrupt",
                "event_id": "0",
                "event_status": "interrupt",
                "content_type": "contexts",
                "visible_scope": "",
                "outputs": {
                    "text": {
                        "function_call": {
                            "thought": "用户想要知道今天北京的天气情况，这是一个明确的天气查询需求。根据工具描述，'get_current_weather'工具可以查询中国城市的天气，因此我将使用这个工具来满足用户的需求。",
                            "name": "get_current_weather",
                            "arguments": {
                                "location": "Beijing",
                                "unit": "celsius"
                            },
                            "usage": {
                                "prompt_tokens": 581,
                                "completion_tokens": 91,
                                "total_tokens": 672,
                                "name": "ERNIE-3.5-8K",
                                "type": "plan"
                            },
                            "tool_call_id": "4c03ac0d-7cd1-4bde-812f-63fa506c6aea"
                        },
                        "used_tool": [

                        ]
                    }
                },
                "tool_calls": [
                    {
                        "id": "4c03ac0d-7cd1-4bde-812f-63fa506c6aea",
                        "type": "function",
                        "function": {
                            "name": "get_current_weather",
                            "arguments": {
                                "location": "Beijing",
                                "unit": "celsius"
                            }
                        }
                    }
                ]
            }
        ],
        "prototype": "function_call"
    }
}

3. 上报工具调用结果

curl --location --request POST 'https://qianfan.baidubce.com/v2/app/conversation/runs' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "4d4b1b27-d607-4d2a-9002-206134217a9f",
    "stream": false,
    "conversation_id": "8c5928f7-a9e7-4826-a027-3eb1f97f6eab",
    "tool_outputs": [
        {
            "tool_call_id": "ba853313-cbf0-4ecc-8ae7-92b33f00509d",
            "output": "北京今天天气晴朗，温度32度"
        }
    ]
}'

在线调试

AppBuilder提供了API调试平台,支持Python、Java、PHP、C#、Go、Node.js、C++ 7种主流语言示例代码自动生成。同时可以帮助开发者在线调试OpenAPI接口，支持查看在线调用的请求内容和返回结果、复制和下载示例代码等功能，简单易用。

文件上传

应用查询

百度智能云

千帆AppBuilder

千帆AppBuilder

大模型对话

在线调试

接口描述

权限说明

接口定义

请求结构

请求头域

请求参数

响应头域

响应参数

请求curl示例

正确响应示例

错误响应示例

其他示例

1. 强制执行组件

2. Function call本地函数

3. 上报工具调用结果

在线调试