华为云Flexus企业搜索服务完全对接指南：从开通到API集成实战

1. Flexus企业搜索服务概述

华为云Flexus企业搜索服务，产品名称为KooSearch，是华为云基于云搜索服务搭建的一站式智能搜索解决方案。该服务旨在帮助企业聚焦业务场景和应用开发，通过场景服务化、技术简单化、低门槛化的设计理念，满足开发者基于业务场景的二次开发需求。

在技术架构上，KooSearch深度整合了RAG（检索增强生成）能力，为大型语言模型提供外部知识来源，有效扩大知识检索范围。服务依托华为云盘古大模型的海量数据学习迭代，具备行业领先的搜索精度；同时采用分布式搜索服务架构和自研向量检索引擎，提供企业级稳定性，可实现百亿数据毫秒级响应。

目前KooSearch服务仅在西南-贵阳一区域支持开通和使用。服务提供智能搜索版等多种版本规格，其中智能搜索版提供开箱即用的知识库，主要用于RAG场景。此外还支持OCR增强功能，通过引用OCR服务能力来增强实例的搜索和问答能力。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

2. 开通Flexus企业搜索服务

2.1 服务开通前置条件

在使用KooSearch服务之前，需要满足以下前置条件：

• 已注册华为账号并完成实名认证
• 账号不能处于欠费或冻结状态
• 确认服务区域为西南-贵阳一

2.2 开通操作步骤

开通Flexus企业搜索服务的具体操作如下：

1. 登录云搜索服务管理控制台
2. 在左侧导航栏选择“KooSearch > Flexus企业搜索服务”，进入Flexus企业搜索服务页面
3. 单击页面右上角的“购买Flexus企业搜索服务”按钮，进入购买页面

2.3 购买配置参数说明

在购买页面需要完成以下配置：

购买时长方面，支持按月购买，购买周期越长价格越优惠。如果购买时长超过3个月，建议包年购买以获得更优惠的价格，也可以勾选自动续费复选框。

3. 在控制台使用KooSearch实现搜索问答

开通服务后，可以在KooSearch控制台实现搜索问答功能。整体使用流程如下：

3.1 创建和管理模型服务（可选）

当KooSearch服务管理员需要自定义模型服务时，可以创建和管理KooSearch模型服务。如果不需要自定义模型，可以跳过此步骤直接使用系统默认模型。

3.2 创建KooSearch知识库

知识库是KooSearch服务的核心组成部分，用于存储和管理文档数据。创建知识库的操作如下：

1. 登录云搜索服务管理控制台
2. 在左侧导航栏选择“KooSearch > Flexus企业搜索服务”
3. 单击已创建的服务实例名称进入详情页
4. 在知识库管理页面单击“创建知识库”

创建成功后，可以查看知识库列表，包括知识库ID、知识库名称、知识库状态、创建人、创建时间、更新时间等信息。知识库ID是后续API调用中的重要参数，具有唯一性。

3.3 上传文件至知识库

创建知识库后，可以将本地文件上传至知识库。KooSearch支持多种文件格式的文档上传，并会自动进行文档解析和分片处理，以便于后续的搜索和问答。

此外，KooSearch还支持无缝对接FTP、OBS、HBase、Kafka等多种数据源，仅需简单配置即可完成数据接入，无需编程。服务支持每天百TB级数据入库，提供PB级以上数据处理能力。

3.4 体验KooSearch问答

文档上传完成后，可以在KooSearch控制台体验智能问答功能。操作步骤如下：

1. 登录云搜索服务管理控制台
2. 在左侧导航栏选择“KooSearch > KooSearch文档问答”
3. 选择已创建好的文档问答服务，单击操作列的“问答”，前往KooSearch控制台

在问答体验页面，可以输入问题并获取基于知识库内容的智能回答。页面上还提供了“对话配置”和“对话清空”等按钮，方便进行对话管理。

3.5 体验KooSearch搜索

除了问答功能，KooSearch还提供了纯粹的搜索能力。用户可以根据关键词在知识库中搜索相关文档片段，搜索结果会按相关性排序返回。

4. 通过API使用KooSearch实现搜索问答

对于开发者而言，通过API集成KooSearch服务是实现企业级应用的关键路径。KooSearch服务提供了REST风格API，支持通过HTTPS请求调用。

4.1 API调用基础

4.1.1 终端节点（Endpoint）

终端节点即调用API的请求地址。不同服务在不同区域有不同的Endpoint。由于KooSearch服务目前仅支持西南-贵阳一区域，其Endpoint为iam.cn-southwest-2.myhuaweicloud.com。

4.1.2 请求方法

KooSearch API支持以下HTTP请求方法：

• GET：请求服务器返回指定资源
• PUT：请求服务器更新指定资源
• POST：请求服务器新增资源或执行特殊操作
• DELETE：请求服务器删除指定资源
• HEAD：请求服务器资源头部
• PATCH：请求服务器更新资源的部分内容

4.1.3 公共请求消息头

调用KooSearch API时需要设置以下公共请求头：

Token获取方式请参考“获取IAM用户Token”接口。调用该接口获取Token后，在请求消息头中携带X-Auth-Token字段进行认证。

4.1.4 请求URL结构

API请求URL的结构如下：

{URI-scheme}://{Endpoint}/{resource-path}

其中URI-scheme为HTTPS协议，Endpoint为服务端域名，resource-path为API访问路径。

4.2 核心API接口详解

4.2.1 搜索知识库

搜索知识库是KooSearch最核心的API接口之一，用于根据查询词在指定知识库中搜索相关的文档分片。

接口信息：

• URI：POST /v1/koosearch/experience/search
• 请求方式：POST

请求Header参数：

请求Body参数：

filter_string语法说明：

• 支持布尔运算符AND、OR和NOT（也可写作&&、||和!）
• 多个运算符同时使用时建议使用括号明确优先级
• 保留字符需要使用反斜杠转义：+ - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /
• 示例：tags:(魔都 OR 首都) AND category:"城市(city)"

4.2.2 知识库管理API

知识库管理API用于创建、查询、更新和删除知识库。

查看知识库列表：

• 功能介绍：查看知识库列表，包括知识库ID、知识库名称、知识库状态、创建人、创建时间、更新时间等

标签管理：

• 知识库支持标签管理，可以通过tags参数添加标签

4.2.3 FAQ管理API

FAQ管理API支持常见问答对的批量管理：

• 获取FAQ列表：根据知识库ID获取FAQ列表，可按问题关键字过滤
• 批量FAQ上传：支持批量上传FAQ文件
• 下载上传失败的FAQ：可下载导入失败的FAQ文件进行修正
• 批量删除FAQ：支持批量删除FAQ

4.2.4 模型管理API

模型管理API用于管理和配置NLP模型：

• 新增模型：创建新的NLP模型配置
• 修改模型配置：更新已有模型的配置信息

模型配置参数包括模型名称、类型、endpoint、部署ID、IAM鉴权信息等。

4.2.5 对话历史管理API

对话历史管理API支持对话记录的查询和删除：

• 批量删除对话历史：根据对话ID批量删除对话历史信息

4.3 Python调用示例

以下是一个完整的Python示例，演示如何调用KooSearch的搜索知识库API：

# coding=utf-8
import requests
import json

# IAM认证配置
iam_url = "https://iam.cn-southwest-2.myhuaweicloud.com/v3/auth/tokens"
iam_payload = {
    "auth": {
        "identity": {
            "methods": ["password"],
            "password": {
                "user": {
                    "name": "your_username",
                    "password": "your_password",
                    "domain": {
                        "name": "your_domain_name"
                    }
                }
            }
        },
        "scope": {
            "project": {
                "name": "cn-southwest-2"
            }
        }
    }
}

# 获取Token
response = requests.post(iam_url, json=iam_payload)
token = response.headers.get("X-Subject-Token")

# KooSearch API配置
search_url = "https://{endpoint}/v1/koosearch/experience/search"
headers = {
    "Content-Type": "application/json",
    "X-Auth-Token": token
}

# 搜索请求参数
search_payload = {
    "repo_id": "your_knowledge_base_id",
    "content": "搜索关键词",
    "page_num": 1,
    "page_size": 10,
    "scope": "doc"
}

# 发起搜索请求
response = requests.post(search_url, headers=headers, json=search_payload)

if response.status_code == 200:
    result = response.json()
    print("搜索结果：", json.dumps(result, ensure_ascii=False, indent=2))
else:
    print("搜索失败，状态码：", response.status_code)
    print("错误信息：", response.text)

4.4 Java调用示例

以下是Java语言调用KooSearch API的示例：

import okhttp3.*;
import org.json.JSONObject;

public class KooSearchExample {
    public static void main(String[] args) throws Exception {
        // IAM认证配置
        String iamUrl = "https://iam.cn-southwest-2.myhuaweicloud.com/v3/auth/tokens";
        JSONObject iamPayload = new JSONObject();
        JSONObject auth = new JSONObject();
        JSONObject identity = new JSONObject();
        identity.put("methods", new String[]{"password"});
        
        JSONObject password = new JSONObject();
        JSONObject user = new JSONObject();
        user.put("name", "your_username");
        user.put("password", "your_password");
        
        JSONObject domain = new JSONObject();
        domain.put("name", "your_domain_name");
        user.put("domain", domain);
        password.put("user", user);
        identity.put("password", password);
        auth.put("identity", identity);
        
        JSONObject scope = new JSONObject();
        JSONObject project = new JSONObject();
        project.put("name", "cn-southwest-2");
        scope.put("project", project);
        auth.put("scope", scope);
        iamPayload.put("auth", auth);
        
        OkHttpClient client = new OkHttpClient();
        
        // 获取Token
        RequestBody iamBody = RequestBody.create(
            MediaType.parse("application/json"),
            iamPayload.toString()
        );
        Request iamRequest = new Request.Builder()
            .url(iamUrl)
            .post(iamBody)
            .build();
        
        Response iamResponse = client.newCall(iamRequest).execute();
        String token = iamResponse.header("X-Subject-Token");
        
        // KooSearch搜索请求
        String searchUrl = "https://{endpoint}/v1/koosearch/experience/search";
        JSONObject searchPayload = new JSONObject();
        searchPayload.put("repo_id", "your_knowledge_base_id");
        searchPayload.put("content", "搜索关键词");
        searchPayload.put("page_num", 1);
        searchPayload.put("page_size", 10);
        searchPayload.put("scope", "doc");
        
        RequestBody searchBody = RequestBody.create(
            MediaType.parse("application/json"),
            searchPayload.toString()
        );
        
        Request searchRequest = new Request.Builder()
            .url(searchUrl)
            .header("Content-Type", "application/json")
            .header("X-Auth-Token", token)
            .post(searchBody)
            .build();
        
        Response searchResponse = client.newCall(searchRequest).execute();
        if (searchResponse.isSuccessful()) {
            String result = searchResponse.body().string();
            System.out.println("搜索结果：" + result);
        } else {
            System.out.println("搜索失败，状态码：" + searchResponse.code());
        }
    }
}

5. 高级功能与最佳实践

5.1 自定义Prompt配置

KooSearch支持设置知识库搜索问答的prompt。该prompt包括参考文献占位符{0}和搜索query占位符{1}。通过配置不同的prompt，可以实现以下效果：

• 增加人设设定，使回答更符合特定角色
• 添加限定条件，约束回答范围
• 指定答案格式要求，使输出更规范
• 根据不同的使用场景配置不同的prompt，帮助模型生成更优的结果

5.2 文档解析规则自定义

KooSearch支持用户自定义文档解析规则。解析规则用于解析需要作为subtitle的文本，规则由上而下依次校验。通过自定义解析规则，可以更精准地控制文档的分片方式和内容提取。

5.3 日志管理与问题定位

为了方便用户使用日志定位问题，KooSearch服务提供了日志查询功能。用户可以通过日志查询进行问题分析定位。日志查询操作如下：

1. 进入KooSearch服务详情页面
2. 登录云搜索服务管理控制台
3. 在左侧导航栏选择“KooSearch > Flexus企业搜索服务”

5.4 集群路由配置

Flexus企业搜索服务支持配置集群路由。在服务详情页面，单击集群路由右侧的“修改”按钮，可以修改集群路由信息。

5.5 服务删除与资源释放

当不再需要使用KooSearch服务时，可以删除服务释放资源。需要注意以下事项：

• 删除服务时会清理业务数据，同时删除依赖集群
• 包年包月计费方式的服务支持退订/释放
• 退订/释放服务后资源释放且数据清空，无法恢复
• 请谨慎操作

5.6 API发布与环境管理

KooSearch服务开通成功后，会自动创建KooSearch API。在KooSearch服务详情页的API管理页签，可以看到两类API：知识库API和文档解析API。

将KooSearch API发布到不同环境后，支持在环境中调用API使用KooSearch服务。发布流程如下：

1. 在APIG服务配置API网关
2. 在CSS服务发布KooSearch API

5.7 与第三方平台集成

KooSearch知识库可以与其他平台集成使用。例如，通过AgentArts调用KooSearch知识库会消耗KooSearch的API调用次数及流量。第三方KooSearch的拥有者需要发布搜索知识库和获取知识库列表两个API接口，供后续使用者在AgentArts平台调用。

此外，KooSearch还可以与Dify等开源LLM应用开发平台集成，将创建的知识库挂载至华为云对象存储服务（OBS）桶，实现知识数据的统一管理与持久化存储。

6. 成本优化与安全管理

6.1 计费模式

Flexus企业搜索服务支持按月和按年两种计费方式。主要计费项包括：

• 实例费用：根据购买时长和规格计费
• API调用次数：超出免费额度后按次计费

6.2 成本优化建议

• 购买时长超过3个月建议选择包年方式，价格更优惠
• 合理规划知识库规模，避免不必要的存储费用
• 监控API调用量，防止超出免费额度产生额外费用

6.3 安全管理

• 使用IAM Token进行API认证，确保接口调用安全
• 通过VPC、子网、安全组进行网络隔离
• 企业项目支持资源的分组和管理
• 服务删除前务必确认数据已备份

7. 常见问题解答

问1：Flexus企业搜索服务支持哪些区域？
答：目前仅支持西南-贵阳一区域开通和使用KooSearch服务。

问2：如何获取知识库ID？
答：登录KooSearch体验平台，在左侧导航栏选择“知识库管理”，在此界面获取“知识库ID”字段的值。

问3：KooSearch API调用需要什么认证方式？
答：使用IAM Token认证方式。先调用IAM接口获取Token，然后在API请求的Header中携带X-Auth-Token字段。

问4：搜索API的filter_string参数有什么作用？
答：filter_string是带语法的查询字符串，支持布尔运算AND、OR、NOT，可以用于精确过滤搜索结果。

问5：删除Flexus企业搜索服务会有什么影响？
答：删除服务时会清理业务数据，也会删除依赖集群，数据无法恢复，请谨慎操作。

问6：KooSearch支持哪些数据源的接入？
答：支持无缝对接FTP、OBS、HBase、Kafka等多种数据源，仅需简单配置即可完成数据接入。