第三方服务业务信息透传最佳实践
第三方服务业务信息透传
功能概述
大模型实时互动服务，支持人设、话题等场景配置使用第三方模型服务，也支持为Function Call配置接收HTTP回调服务地址。如果需要系统在请求这些第三方服务时携带额外的业务信息（如鉴权凭证、业务上下文、模型参数配置等），可通过在创建智能体接口或客户端信令中使用tp_extra_data字段配置透传参数，系统会在调用这些第三方时会携带对应的header参数、url参数或body请求体参数。
支持透传的字段名：
| 字段名 | 参数描述 |
|---|---|
| sceneRole | 对人设使用第三方模型生效 |
| topic | 对话题配置的OpenAI协议服务生效 |
| functionCall | 对Function Call配置的HTTP回调服务器生效 |
数据结构说明
ThirdPartyServiceExtraData
| 参数名 | 参数类型 | 必要性 | 参数描述 |
|---|---|---|---|
| sceneRole | HttpExtraData | 否 | 人设第三方模型透传参数 |
| topic | HttpExtraData | 否 | 话题模型服务透传参数 |
| functionCall | HttpExtraData | 否 | Function Call HTTP 回调透传参数 |
HttpExtraData
| 参数名 | 参数类型 | 必要性 | 参数描述 |
|---|---|---|---|
| headerMap | Map<String, String> | 否 | 请求第三方服务时，header中的额外参数 |
| paramMap | Map<String, String> | 否 | 请求第三方服务时，URL查询参数中的额外参数 |
| bodyMap | Map<String, Object> | 否 | 请求第三方服务时，body中的额外字段，value支持JSON Object |
配置方式
创建智能体时配置
在创建智能体时，通过config中的 tp_extra_data字段设置透传信息, 可参考接口地址。
config 示例
1{
2 "tp_extra_data": {
3 "functionCall": {
4 "headerMap": {
5 "h1": "v1"
6 },
7 "paramMap": {
8 "p1": "v1"
9 },
10 "bodyMap": {
11 "b1": "v1"
12 }
13 },
14 "sceneRole": {
15 ...
16 },
17 "topic": {
18 ...
19 }
20 }
21}创建智能体请求示例
1{
2 "app_id": "app*********",
3 "config": "{\"tp_extra_data\":{\"functionCall\":{\"headerMap\":{\"h1\":\"v1\"},\"paramMap\":{\"p1\":\"v1\"},\"bodyMap\":{\"b1\":\"v1\"}},\"sceneRole\":{...},\"topic\":{...}}}"
4}注意：config字段类型为String字符串，是json对象序列化后的string类型。
信令动态更新
智能体运行期间，可通过信令事件动态更新透传参数值，无需重新创建智能体。
信令格式
1[SET]:[TP_EXTRA_DATA]:{json_content}更新参数 JSON 示例
1{
2 "tp_extra_data": {
3 "functionCall": {
4 "headerMap": {
5 "h1": "v1",
6 "h2": "v2"
7 },
8 "bodyMap": {
9 "b1": "v3",
10 "b2": "v4",
11 "b3": {
12
13 }
14 }
15 }
16 }
17}更新信令示例
1[SET]:[TP_EXTRA_DATA]:{"tp_extra_data":{"functionCall":{"headerMap":{"h1":"v1","h2":"v2"},"bodyMap":{"b1":"v3","b2":"v4","b3":{}}}}}更新逻辑说明
- 增量更新：只更新信令中指定的子模块和字段，未指定的保持不变
- 字段覆盖：相同key的值以新值覆盖旧值
- 模块独立：每个子模块（sceneRole/topic/functionCall）独立更新，互不影响
示例：若当前sceneRole.headerMap为{"h1":"v1", "h2":"v2"}，更新{"h1":"v1-new", "h3":"v3"}后，结果为{"h1":"v1-new", "h2":"v2", "h3":"v3"}（h1 被覆盖，h2 保持不变，h3 为新增）。
应用场景
应用场景1：透传鉴权信息
当您配置了Function Call HTTP回调服务器时，回调接收端通常需要对请求来源进行合法性校验。您可以通过functionCall.headerMap透传apiKey，接收端从header中取出并校验其是否有效。
如下是通过functionCall.headerMap透传鉴权信息的示例：
1{
2 "functionCall": {
3 "headerMap": {
4 "X-Api-Key": "sk-xxxxxxxxxxxx"
5 }
6 }
7}应用场景2： 传递模型参数配置
当您使用第三方模型服务（如Qwen、千帆等）时，可能需要对模型请求参数进行定制化配置。通过bodyMap可以向模型请求体中注入额外字段，这些字段会在调用模型服务时直接合并到请求body中。
以下示例展示了如何通过sceneRole.bodyMap关闭模型的思考（thinking）能力，并关闭usage用量统计的返回：
1{
2 "sceneRole": {
3 "bodyMap": {
4 "stream_options": {
5 "include_usage": false
6 },
7 "enable_thinking": false
8 }
9 }
10}评价此篇文章