妙搜API最佳实践
本文提供妙搜链路 API的最佳示例，帮助您快速入门并开发您自己的业务应用。
一、妙搜功能概述
1.1、一句话说明
妙搜内置“互联网搜索”，可以供通用领域知识、信息智能搜索生成，为了应对更多领域、企业知识的搜索生成，我们提供了“三方搜索API”和“企业知识”的集成能力。通过以下接口可以配置和管理企业API和知识。控制台入口：
1.2、产品页面展示
1.2.1、数据源管理
控制台入口
对应“数据源管理”菜单：此菜单下为数据接入说明，支持PaasAPI方式维护数据源和数据集下知识。
功能说明
维护数据源，可以是多个，供“智能搜索”模块搜索获取知识。支持的数据源类型目前有三种：
系统内置数据源：系统内置，不支持修改，目前内置“互联网搜索”，支持互联网通用领域的网站数据搜索；
三方搜索API数据源：企业提供搜索API，妙搜提供大模型能力并整合，目前需联系后台技术维护，暂未开放自定义；
企业知识数据源：企业提供知识，妙搜提供搜索和大模型能力，可以通过“数据源管理”下数据集相关API维护索引和索引中知识。
API：数据源管理（仅混合云，公有云待上线）
1.2.2、系统配置->通用/媒资搜索信源
控制台入口
对应“系统配置”菜单下“通用搜索信源”、“媒资搜索信源”两个tab。
功能说明
维护“智能搜索”模块两个tab下索引的启用与否、召回文章、chunk（片段）条数。
API：系统配置-信源管理
1.2.3、智能搜索
控制台入口
妙搜首页下多模态搜索框。
妙笔首页右上角搜索素材。
功能说明
深度服务通用领域，影视、媒体、营销、影视、媒体等行业的多模态搜索。
API：智能搜索
chatconfig.SearchSource 字段下配置“数据源（信源）”。
二、PaasAPI整体对接方案
2.1、方案概览
2.2、接口明细
三、PaasAPI对接示例
3.1、前提条件
阿里云账号已开通本产品；
获得AgentKey、AccessKeyId、AcccessKeySecret：AccessKey、AppID及AgentKey获取方式；
获取WorkSpaceId 获取Workspace ID；
引入妙笔SDK 注意获取最新sdk版本；
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aimiaobi20230801</artifactId>
<version>${latest}</version>
</dependency>引入三方依赖：本文SSE示例采用okhttp开源三方组件，如果使用示例代码需要引入如下pom。
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.9.1</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp-sse</artifactId>
<version>4.9.1</version>
</dependency>3.2、管控API（HTTP）-CreateToken
准备：
阿里云账号已开通产品；
获取AccessKey：对应示例中 ALIBABA_CLOUD_ACCESS_KEY_ID；
获取AccessKeySecret：对应示例中 ALIBABA_CLOUD_ACCESS_KEY_SECRET；
获取AgentKey：对应示例中 AgentKey；
接口文档
接口说明
获取推理API依赖的访问鉴权token；
获取到授权token 注意：token有效期，时效为三分钟。
在线调试&示例：
调用示例
Java-SDK：
import com.aliyun.aimiaobi20230801.models.CreateTokenRequest;
import com.aliyun.aimiaobi20230801.Client;
import com.aliyun.teaopenapi.models.Config;
public class Sample {
/**
* <b>description</b> :
* <p>使用AK&SK初始化账号Client</p>
* @return Client
*
* @throws Exception
*/
public static Client createClient() throws Exception {
// 工程代码泄露可能会导致 AccessKey 泄露，并威胁账号下所有资源的安全性。以下代码示例仅供参考。
// 建议使用更安全的 STS 方式，更多鉴权访问方式请参见：https://help.aliyun.com/document_detail/378657.html。
Config config = new Config()
// 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
// 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// Endpoint 请参考 https://api.aliyun.com/product/AiMiaoBi
config.endpoint = "aimiaobi.cn-beijing.aliyuncs.com";
return new Client(config);
}
public static void main(String[] args) throws Exception {
Client client = createClient();
CreateTokenRequest createTokenRequest = new CreateTokenRequest();
createTokenRequest.setAgentKey("AgentKey");
try {
// 复制代码运行请自行打印 API 的返回值
client.createToken(createTokenRequest);
} catch (Exception e) {
// 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
e.printStackTrace();
}
}
}
3.3、推理API（HTTP-SSE）-chatGenerate
准备
阿里云账号已开通产品；
获取AccessKey：对应示例中 ALIBABA_CLOUD_ACCESS_KEY_ID；
获取AccessKeySecret：对应示例中 ALIBABA_CLOUD_ACCESS_KEY_SECRET；
获取AgentKey：对应示例中 AgentKey；
通过CreateToken获取鉴权token：放入请求header中：Authorization: Bearer {token} 。
接口文档
接口地址
https://aimiaobi.aliyuncs.com/api/llm/gc/chatGenerate。
接口说明
妙搜-智能搜索接口。
调用示例
Java-SDK：
import com.aliyun.aimiaobi20230801.Client;
import com.aliyun.aimiaobi20230801.models.CreateTokenResponse;
import com.aliyun.teaopenapi.models.Config;
import okhttp3.*;
import okhttp3.internal.sse.RealEventSource;
import okhttp3.sse.EventSource;
import okhttp3.sse.EventSourceListener;
import java.util.concurrent.TimeUnit;
public class Sample {
/**
* <b>description</b> :
* <p>使用AK&SK初始化账号Client</p>
* @return Client
*
* @throws Exception
*/
public static Client createClient() throws Exception {
// 工程代码泄露可能会导致 AccessKey 泄露，并威胁账号下所有资源的安全性。以下代码示例仅供参考。
// 建议使用更安全的 STS 方式，更多鉴权访问方式请参见：https://help.aliyun.com/document_detail/378657.html。
Config config = new Config()
// 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
// 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// Endpoint 请参考 https://api.aliyun.com/product/AiMiaoBi
config.endpoint = "aimiaobi.cn-beijing.aliyuncs.com";
return new Client(config);
}
/**
* 获取鉴权token
* @return
*/
private static String createToken() throws Exception {
com.aliyun.aimiaobi20230801.Client client = createClient();
com.aliyun.aimiaobi20230801.models.CreateTokenRequest createTokenRequest = new com.aliyun.aimiaobi20230801.models.CreateTokenRequest();
createTokenRequest.setAgentKey("AgentKey");
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// 复制代码运行请自行打印 API 的返回值
CreateTokenResponse createTokenResponse = client.createTokenWithOptions(createTokenRequest, runtime);
return createTokenResponse.getBody().getData().getToken();
}
public static void chatGenerate(String token) throws Exception {
String url = "https://aimiaobi.aliyuncs.com/api/llm/gc/chatGenerate";
//构建请求参数
String requestBodyJson = "{\n" +
" \"prompt\": \"杭州亚运会吉祥物\",\n" +
" \"chatConfig\": {\n" +
" \"generateTechnology\": \"copilotReference\",\n" +
" \"searchModels\": [\n" +
" \"TextGenerate\"\n" +
" ]\n" +
" }\n" +
"}";
RequestBody requestBody = RequestBody.create(MediaType.parse("application/json"), requestBodyJson);
//构建SSE请求
Request request = new Request.Builder()
.url(url)
.header("Authorization", "Bearer " + token)
.post(requestBody)
.build();
// 定义OkHttpClient
OkHttpClient okHttpClient = new OkHttpClient.Builder()
.connectTimeout(1, TimeUnit.MINUTES)
.readTimeout(1, TimeUnit.MINUTES)
.build();
// 实例化EventSource，注册EventSource监听器
RealEventSource realEventSource = new RealEventSource(request, new EventSourceListener() {
private long callStartNanos;
private void printEvent(String name) {
long nowNanos = System.nanoTime();
if (name.equals("callStart")) {
callStartNanos = nowNanos;
}
long elapsedNanos = nowNanos - callStartNanos;
System.out.printf("=====> %.3f %s%n", elapsedNanos / 1000000000d, name);
}
@Override
public void onOpen(EventSource eventSource, Response response) {
printEvent("onOpen");
}
@Override
public void onEvent(EventSource eventSource, String id, String type, String data) {
printEvent("onEvent");
//响应到的报文：todo 这里做业务逻辑处理
System.out.println(data);
}
@Override
public void onClosed(EventSource eventSource) {
printEvent("onClosed");
}
@Override
public void onFailure(EventSource eventSource, Throwable t, Response response) {
//这边可以监听并重新打开
printEvent("onFailure");
}
});
//真正开始请求的一步
realEventSource.connect(okHttpClient);
}
public static void main(String[] args) {
try {
chatGenerate(createToken());
} catch (Exception e) {
//处理异常
e.printStackTrace();
}
}
}CURL：
curl 'https://aimiaobi.aliyuncs.com/api/llm/gc/chatGenerate' \
-X 'POST' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer {token}' \
--data '{
"prompt": "杭州亚运会吉祥物",
"chatConfig": {
"generateTechnology": "copilotReference",
"searchModels": [
"TextGenerate"
],
"searchParam": {
"searchSources": [
{
"code": "SystemSearch",
"datasetName": "QuarkCommonNews"
}
]
}
}
}'请求参数json样例：
{
"prompt": "杭州亚运会吉祥物",
"chatConfig": {
"generateTechnology": "copilotReference",
"searchModels": [
"TextGenerate"
],
"searchParam": {
"searchSources": [
{
"code": "SystemSearch",
"datasetName": "QuarkCommonNews"
}
]
}
}
}关键参数说明：
chatConfig.generateTechnology：搜索模式：copilotReference：通用搜索；copilotPrecise：媒资搜索；
chatConfig.searchModels：搜索类型（Agent），比如：TextGenerate 总结生成答案；
chatConfig.searchParam.searchSources：搜索信源。
响应示例
id:32c02e8e-3498-4765-878e-2125fd5e7caa
event:task-finished
data:{
"payload": {
"output": {
"agentContext": {
"bizContext": {
"prompt": "杭州亚运会吉祥物",
"currentStep": "search",
"nextStep": "generate",
"searchKeywords": [
"杭州",
"亚运会",
"吉祥物"
],
"supplementEnable": false,
"supplementDataType": "searchQuery",
"searchQueryList": [
"杭州亚运会吉祥物"
],
"multimodalMediaSelection": {},
"generatedContent": {
"textSearchResult": {
"total": 10,
"searchQuery": "杭州亚运会吉祥物",
"searchResult": [
{
"docUuid": "53558a72452efbe881f41e81bd6138fe",
"chunks": [
"AI知识君全网内容智能分析杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，分别是琮、莲莲和宸宸。\n1. \n琮琮：代表位于浙江省杭州市余杭区瓶窑镇内的良渚古城遗址。它的名字来源于良渚古城遗址出土的代表性文物玉琮，具有坚强刚毅、敦厚善良、体魄强健和热情奔放四大美好寓意。\n2. \n莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。\n3. 宸宸：代表世界上里程最长、工程量最大的古代运河京杭大运河。宸宸这一名字源于京杭大运河上的著名建筑拱宸桥，其寓意为机智勇敢、聪慧灵动、乐观向上、积极进取。\n",
"2. \n莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。\n3. 宸宸：代表世界上里程最长、工程量最大的古代运河京杭大运河。宸宸这一名字源于京杭大运河上的著名建筑拱宸桥，其寓意为机智勇敢、聪慧灵动、乐观向上、积极进取。",
"3. 宸宸：代表世界上里程最长、工程量最大的古代运河京杭大运河。宸宸这一名字源于京杭大运河上的著名建筑拱宸桥，其寓意为机智勇敢、聪慧灵动、乐观向上、积极进取。\n参考来源[1]琮琮（杭州第19届亚运会吉祥物）_百度百科百度百科[2]杭州亚运会吉祥物分别代表什么 一文详解2022年亚运会吉祥物美好寓意qtx.com\n杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，分别是琮琮、莲莲和宸宸。\n1. \n琮琮：代表位于浙江省杭州市余杭区瓶窑镇内的良渚古城遗址。它的名字来源于良渚古城遗址出土的代表性文物玉琮，具有坚强刚毅、敦厚善良、体魄强健和热情奔放四大美好寓意。\n2. \n莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。\n"
],
"index": 1,
"searchSourceType": "SystemSearch",
"searchSource": "QuarkCommonNews",
"searchSourceName": "互联网搜索",
"pubTime": "2024-08-09 05:48:52",
"source": "百度百科",
"title": "杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，分别是琮琮、莲莲和宸宸。<",
"content": "AI知识君全网内容智能分析杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，分别是琮琮、莲莲和宸宸。\n1. \n琮琮：代表位于浙江省杭州市余杭区瓶窑镇内的良渚古城遗址。它的名字来源于良渚古城遗址出土的代表性文物玉琮，具有坚强刚毅、敦厚善良、体魄强健和热情奔放四大美好寓意。\n2. \n莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。\n3. 宸宸：代表世界上里程最长、工程量最大的古代运河京杭大运河。宸宸这一名字源于京杭大运河上的著名建筑拱宸桥，其寓意为机智勇敢、聪慧灵动、乐观向上、积极进取。\n参考来源[1]琮琮（杭州第19届亚运会吉祥物）_百度百科百度百科[2]杭州亚运会吉祥物分别代表什么 一文详解2022年亚运会吉祥物美好寓意qtx.com\n杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，分别是琮琮、莲莲和宸宸。\n1. \n琮琮：代表位于浙江省杭州市余杭区瓶窑镇内的良渚古城遗址。它的名字来源于良渚古城遗址出土的代表性文物玉琮，具有坚强刚毅、敦厚善良、体魄强健和热情奔放四大美好寓意。\n2. \n莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。\n3. 宸宸：代表世界上里程最长、工程量最大的古代运河京杭大运河。宸宸这一名字源于京杭大运河上的著名建筑拱宸桥，其寓意为机智勇敢、聪慧灵动、乐观向上、积极进取。",
"url": "https://page.sm.cn/blm/midpage-317/index?h=v7.wenda_llm.quark.cn&id=24_bef1416cd6f6aedf89355fa42e67cb20&from=kkframenew",
"summary": "杭州第19届亚运会的吉祥物是三个造型活泼可爱且又充满时代活力的机器人形象，<em>分别是琮琮、莲莲和宸宸</em>。<br>1. 琮琮：代表位于浙江省杭州市余杭区瓶窑镇内的良渚古城遗址。它的名字来源于良渚古城遗址出土的代表性文物玉琮，具有坚强刚毅、敦厚善良、体魄强健和热情奔放四大美好寓意。<br>2. 莲莲：代表杭州的城市名片西湖，结合吉祥物莲莲身上的主色调，人们自然会想到西湖上的接天莲叶。这一吉祥物形象除了寓意纯洁善良、活泼可爱、热情好客、美丽动人外，还寄托了莲花那高贵、纯洁的美好品质。<br",
"select": true,
"score": 1.0,
"rankScore": 2.6661994,
"isChunk": true
}
]
}
}
},
"agentName": "PlannerAgent"
}
},
"usage": {
"totalTokens": 693
}
},
"header": {
"sessionId": "32c02e8e-3498-4765-878e-2125fd5e7caa",
"taskId": "67a91c00-54aa-4684-8eb3-cb9951cb8382",
"event": "task-finished",
"show": true,
"eventInfo": "生成完成",
"responseTime": 7525
}
}说明
关注event:task-finished：标识搜索生成完成。
四、业务场景最佳实践
4.1、场景一：互联网智能搜索
场景说明
无企业专属知识，走互联网通用领域知识进行智能搜索生成。
技术对接步骤
配置信源：
“1.2.2、系统配置->通用/媒资搜索信源”下配置“互联网搜索”的开启&条数。
对接智能搜索API：
“1.2.3、智能搜索”模块下API，指定“互联网搜索”数据集作为搜索源。
4.2、场景二：企业搜索API智能搜索
场景说明
企业有自己的搜索能力（可以是企业知识库搜索，也可以是三方通用领域搜索等），并提供了搜索API，可以走三方企业搜索API接入，加持妙搜大模型能力后，实现灵活的企业级智能搜索生成。
技术对接步骤：
准备三方企业搜索API：
按照推荐的API模板提供API（非标、或不支持的鉴权需要定开）：三方搜索API模板。
配置三方企业搜索API：
提供账号、API定义给技术团队后台维护（未来会开放自定义三方API的维护能力）。
配置信源：
“1.2.2、系统配置->通用/媒资搜索信源”下配置对应索引的开启&条数。
对接智能搜索API：
“1.2.3、智能搜索”模块下API，指定对应数据集作为搜索源。
4.3、场景三：企业知识库智能搜索
场景说明：
有企业知识需要语义构建索引，或已有企业知识搜索能力效果不理想，可以考虑直接通过妙搜构建企业知识库语义索引，用来企业知识库智能搜索生成。
技术对接步骤：
数据对接：通过“1.2.1、数据源管理”模块下维护企业知识语义索引。
如果是poc或者临时固定数据集构建，可以联系技术团队后台批量导入
通过API构建：
数据集-新增接口：初始化一个新的数据集（全局一次）可以手动（curl）一次性提前创建好。
数据集-添加文档数据接口：往步骤i创建的数据集中添加企业知识。
配置信源：
“1.2.2、系统配置->通用/媒资搜索信源”下配置对应索引的开启&条数。
对接智能搜索API：
“1.2.3、智能搜索”模块下API，指定对应数据集作为搜索源。