华为云用户手册

调用已发布的 KooSearch API 在业务环境中调用已发布的KooSearch API。 构造API请求，KooSearch API的请求说明请参见《KooSearch API参考》。 为API请求添加认证信息。 表2 认证方式 认证方式 API请求参数配置 APP认证 表示由API网关服务负责接口请求的安全认证。推荐使用APP认证方式。 关于使用APP认证的方法，具体请参考使用APP认证调用API。 华为 IAM 认证 表示借助IAM服务进行安全认证。 关于IAM认证的方法，具体请参考使用IAM认证调用API。 说明： 选择“华为IAM认证”时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。

升级前检查 为了保证升级成功，需要做升级前检查，升级前检查主要包括如下事项： 表1 升级前检查项 检查项 检查方式 描述 正常状态 集群状态 系统检查 升级任务启动后，系统会自动检查集群状态。“集群状态”为“可用”，表示集群可以正常提供服务。 “集群状态”为“可用”。 资源充足 系统检查 升级任务启动后，系统会自动检查资源。升级过程中会切换OS镜像，需要保证有资源可用。 资源可用且配额充足。 非标操作 人工检查 确认是否存在非标操作。非标操作指的是没有被记录下来的手动操作，这些操作在升级过程中无法自动传递，比如修改系统配置、回程路由等。 未记录到系统中的非标改动，在升级过程中将不会继承下来，升级后可能会影响您的业务，需要提前备份。

场景描述 升级原理 升级过程采用的是one-by-one的方式。升级时，先下线一个节点，然后对该节点执行切换OS镜像的动作，再将已下线节点的网卡port挂载回来，以此保留节点IP地址，再进行初始化节点启动进程，待节点信息更新后，再依次将其余节点镜像进行替换。升级过程中存在节点下线再上线的动作，可能会中断服务，请在业务低峰期执行。 升级流程 进行升级前检查：升级前检查 升级前检查大部分支持系统检查，少部分需要人工检查。 创建升级任务，启动升级：创建升级任务

创建FAQ 在KooSearch控制台，左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 在知识库管理页面，选择已创建的知识库，单击操作列的“文档管理”。 进入“文档管理”页面。 单击“FAQ管理”，切换至“FAQ管理”页签。 单击“创建”，在“新建问答”对话框中输入“标准问题”和“答案”，单击“添加相似问题”，可输入多个相似问题。 在对话框中单击“确认”。 FAQ创建后，可在FAQ管理页签查看已创建的问答。 管理FAQ。 单击操作列的“编辑”，可重新编辑FAQ。 单击操作列的“删除”，可删除已创建的FAQ。

上传结构化数据 提前在本地准备好待上传的结构化数据文件。 支持UTF-8编码的JSONL文件格式，单个文件最大50M，自定义数据长度应在4-1024个字符之间，且文件中仅能使用一种操作。模板如下所示： {"cmd":"ADD","id":"100001","content":"content for the first data"} {"cmd":"ADD","id":"100002","title":"title for the second data","content":"content for the second data","url":"","docTime":"2015/01/01 12:10:30","category":"category1","tags":["tag1","tag2","tag3"]} {"cmd":"UPDATE","id":"100002","content":"The content for the second data is updated","category":"newCategory"} {"cmd":"DELETE","id":"100002"} 在KooSearch控制台，左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 在知识库管理页面，选择已创建的知识库，单击操作列的“文档管理”，进入“文档管理”页面。 单击“结构化数据”，切换至“结构化数据”页签。 单击“上传”，在上传对话框中单击“选择文档”，本地选择已提前准备好的结构化数据文件。 单击“确认”。 文件上传后，可在结构化数据页签查看已上传的文件，当“导入状态”为“正常”，说明文件已上传成功。

上传文档 提前在本地准备好待上传的文档。 支持格式为 .doc, .docx, .pdf, .pptx, .ppt, .xlsx, .xls, .csv, .wps, .png, .jpg, .jpeg, .bmp, .gif, .tiff, .tif, .webp, .pcx, .ico, .psd, .dps, .et, .txt, .ofd 的多个文档，单个文档不能超过128MB（超过60MB建议通过API上传），当前版本中图片上传、文档内单张图片上传最大不超过10MB。 在KooSearch控制台，左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 在知识库管理页面，选择已创建的知识库，单击操作列的“文档管理”，进入“文档管理”页面。 图1 进入文档管理页面 默认进入“文档管理”页签，单击“上传”。 在上传对话框中单击“选择文档”，本地选择已提前准备好的文档。重复的文档不允许上传。 图2 上传文档 单击“确认”。文档上传后，可在文档管理页签查看已上传的文档，当“文档状态”为“正常”，说明文档已上传成功。 文档上传成功后，可以单击文档名称，进入文档信息详情页查看切片效果，单击页面右边的切片内容可以跳转到原文对应的地方（此功能目前只支持.pdf文件）。 图3 单击文档名称 图4 切片效果 管理文档数据。 单击操作列的“下载”，可下载文档至本地。 单击操作列的“删除”，可删除已上传的文档。 单击操作列的“QA生成”，可将上传的文档生成问答模式的Excel文档，生成任务在“任务管理”页签可以查看。 单击操作列的“重试”，可对已上传的文档重新进行切片，生成任务在“任务管理”页签可以查看。

批量导入FAQ 提前在本地准备好待导入的FAQ文件。 主要支持xlsx，xls，docx，doc文件类型格式，文件内容请参考Excel样例文件或Word样例文件。Excel单个文件最大为10MB，单个文件最大支持10000条数据，文件中不允许空行，空行后的数据将被忽略。Word单个文件最大为128M，Word中支持图文格式的FAQ。 在KooSearch控制台，左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 在知识库管理页面，选择已创建的知识库，单击操作列的“文档管理”。 进入“文档管理”页面。 单击“FAQ批量导入”，切换至“FAQ批量导入”页签。 单击“上传”，在上传对话框中单击“选择文档”，本地选择已提前准备好的FAQ文件。 图5 FAQ批量导入 在对话框中单击“确认”。 文件上传后，可在“FAQ批量导入”页签查看已上传的文件，当“导入状态”为“正常”，说明文件已导入成功。 管理FAQ文件。 单击操作列的“下载”，可下载文件至本地。 单击操作列的“删除”，可删除已上传的文件。

场景描述 KooSearch知识库支持上传以下几种类型的知识。 表1 上传数据 上传方式 描述 上传文档 支持上传文档类型的知识，支持格式为 .doc, .docx, .pdf, .pptx, .ppt, .xlsx, .xls, .csv, .wps, .png, .jpg, .jpeg, .bmp, .gif, .tiff, .tif, .webp, .pcx, .ico, .psd, .dps, .et, .txt, .ofd, .md 的多个文档，单个文档不能超过128MB（超过60MB建议通过API上传）。当前版本中图片上传、文档内单张图片上传最大不超过10MB。 创建FAQ 支持创建问答形式的知识。 批量导入FAQ 支持批量导入问答形式的知识，主要支持xlsx，xls，docx，doc文件类型格式。 上传结构化数据 支持上传结构化知识。支持UTF-8编码的JSONL文件格式，单个文件最大50M，自定义数据长度应在4-1024个字符之间，且文件中仅能使用一种操作。

KooSearch文档问答服务使用流程 华为云 企业搜索 KooSearch是基于华为云的 云搜索服务 搭建的一站式智能搜索解决方案，帮助企业聚焦业务场景和应用开发，场景服务化、技术简单化、低门槛化，满足开发者基于业务场景的二次开发。在RAG（Retrieval-Augmented Generation）及搜索场景提供效果和性能突出的组件化服务，架构理想、灵活编排的机制，帮助企业客户快速构建RAG以及搜索服务。 仅“西南-贵阳一”区域支持开通和使用KooSearch服务。KooSearch是白名单功能，如果有试用需求，请提工单申请权限。 KooSearch服务使用流程，如下图所示： 图1 koosearch使用流程 表1 使用流程 步骤 操作 说明 1 开通服务 首先需要开通服务，开通服务时会选择版本规格、配置一系列参数来创建一个实例，后续可以用此实例实现搜索问答，具体请看开通KooSearch文档问答服务。 2 在控制台使用KooSearch服务实现搜索文档 开通服务后，您可以在KooSearch控制台实现搜索问答，具体操作如下： 当KooSearch服务管理员需要自定义模型服务时，可以创建和管理KooSearch模型服务（可选），否则跳过该步骤。 创建KooSearch知识库。 将本地文件上传至KooSearch知识库。 使用KooSearch服务进行问答和搜索。 体验KooSearch问答。 体验KooSearch搜索。 管理知识库。 使用KooSearch的API实现搜索文档 您也可以使用调用API的方式实现搜索问答，KooSearch服务提供的API支持发布到不同的环境，发布成功后支持被调用，具体操作如下： 配置API网关。 发布KooSearch API。 调用已发布的KooSearch API。 编辑API。 下线API。 3 管理KooSearch服务 在服务的基本信息页面，可以获取服务的内网访问文档解析地址、内网访问 知识管理 地址、计费模式等信息。除此之外，还能进行管理服务、API管理和日志管理。具体请看管理KooSearch知识库。 4 查看KooSearch服务日志 为了方便用户使用日志定位问题，KooSearch服务提供了日志查询功能。用户可以通过日志查询进行问题分析定位。具体请看KooSearch文档问答服务日志管理。

版本管理 您创建成功知识库的时候，系统会自动创建一个知识库初始版本，对版本的一些管理操作如下所示： 进入KooSearch控制台。 左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 单击“版本管理”页签。 您创建好知识库后，系统会默认创建一个初始版本。 如果您需要再创建一个版本，单击操作列的“重建”按钮，依次选好参数，即可创建成功。 图3 重建版本 版本名称：版本的名称。 重建来源：选择“索引”或者“文档”。 索引：按照索引重建版本，会直接复用已经完成的向量数据库索引。 文档：按照文档重建版本。选择文档的话，要设置好解析规则是继承原有的规则还是使用最新的规则。 是否立即激活：选择是否立即激活。 描述：对于重建版本的描述。 重建好版本后，可以对版本进行以下操作。 图4 版本操作 状态为“使用中”的版本可进行如下操作： “重建”：按照步骤4重新建一个版本。 “更新”：可以单击此按钮更新版本描述。 状态为“可用”的版本除了“重建”、“更新”还可以进行如下操作： “关闭”：当版本不用时，可以关闭版本释放索引资源。 “删除”：当不再需要此版本时，可以删除版本。 “激活”：可用状态的版本可以激活，激活后此版本的状态变为“使用中”，之前“使用中”的版本状态变为“可用”。 被关闭的版本可进行如下操作： “启用”：被关闭版本如果想再次使用，可以单击此按钮启用，启用后版本状态会变成“可用”。 “删除”：当不再需要此版本时，可以删除版本。 “更新”：可以单击此按钮更新版本描述。

删除知识库 如果无需使用已创建的知识库，可删除知识库释放资源。 删除知识库同时会删除知识库的业务数据，请谨慎操作。 在KooSearch控制台，左侧导航栏选择“知识库管理”。 进入知识库管理页面。 在知识库管理页面，选择已创建的知识库，单击操作列的“删除”，确认需要删除的知识库信息，在输入框输入要删除的知识库名称后，单击“确认”，删除知识库。 在知识库管理页面，选择已创建的知识库，单击操作列的“文档管理”。 进入文档管理页面。 单击页面右上角的“删除”，确认需要删除的知识库信息，在输入框输入要删除的知识库名称后，单击“确认”，删除知识库。

任务管理 在“文档管理”页签单击“QA生成”、“重试”、“全部重试”的任务，都可以在任务管理中查看。“QA生成”的文件可以下载、删除。“重试”、“全部重试”生成的任务只支持删除。 进入KooSearch控制台。 左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 单击“任务管理”页签，勾选需要操作操的任务。可进行下载、删除操作。 图5 任务管理 下载的文档可以在“FAQ批量导入”页签中上传使用。

前提条件 已具备安全模式的Elasticsearch集群和MySQL数据库，且两者在同一个VPC与安全组内。 MySQL数据库中已经有待同步的数据。 本文以如下表结构和初始数据举例。 MySQL中创建一个学生信息表： CREATE TABLE `student` ( `dsc` varchar(100) COLLATE utf8mb4_general_ci DEFAULT NULL, `age` smallint unsigned DEFAULT NULL, `name` varchar(32) COLLATE utf8mb4_general_ci NOT NULL, `id` int unsigned NOT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci; MySQL中插入3个学生的初始数据： INSERT INTO student (id,name,age,dsc) VALUES ('1','Jack Ma Yun','50','Jack Ma Yun is a business magnate, investor and philanthropist.'), ('2','will smith','22','also known by his stage name the Fresh Prince, is an actor, rapper, and producer.'), ('3','James Francis Cameron','68','the director of avatar'); Elasticsearch集群中已完成索引创建，且与MySQL中表相对应。 本文执行如下命令创建Elasticsearch集群的索引。 PUT student { "settings": { "number_of_replicas": 0, "number_of_shards": 3 }, "mappings": { "properties": { "id": { "type": "keyword" }, "name": { "type": "short" }, "age": { "type": "short" }, "desc": { "type": "text" } } } } 其中的“number_of_shards”与“number_of_replicas”需根据具体业务场景进行配置。

应用场景 使用Elasticsearch加速关系型数据库，可以解决关系型数据库在某些方面的局限性，实现更加高效和智能的数据处理和分析。常用于以下应用场景： 电子商务平台：快速搜索商品，提供个性化推荐，实时监控用户行为和交易数据。 内容管理系统：对大量文档和内容进行高效检索，支持复杂的查询和数据分析。 金融服务：实时监控交易数据，进行风险分析和欺诈检测。 社交媒体分析：对用户生成的内容进行情感分析，趋势和影响力评估。 客户关系管理：快速检索客户信息，分析客户行为，提供定制化服务。 日志和事件监控：收集和分析大量日志数据，实时监控系统状态和安全事件。 医疗健康记录：快速检索和分析患者记录，支持临床决策和研究。

方案优势 以下是使用Elasticsearch加速关系型数据库的方案优势： 全文检索能力提升：Elasticsearch是一个提供了强大的全文检索功能的搜索引擎。关系型数据库通常不擅长进行全文检索，而Elasticsearch可以有效地解决这一问题。 高并发Ad Hoc查询：Elasticsearch设计用于处理大量的并发查询请求，特别是在Ad Hoc查询场景下，它能够提供快速的响应时间，从而满足高并发环境下的查询需求。 实时数据同步：通过华为云 数据复制服务 DRS，可以实现MySQL数据库中的数据实时同步到Elasticsearch，确保数据的一致性和实时性。 简化的数据迁移和索引创建：在Elasticsearch中，可以创建与MySQL数据库表结构相对应的索引，简化了数据迁移和索引管理的复杂性。 灵活的查询语言：Elasticsearch提供了灵活的查询语言，支持复杂查询的构建，如范围查询、模糊查询、聚合查询等，这在关系型数据库中可能需要更复杂的SQL语句来实现。 统计分析能力：Elasticsearch的聚合功能可以快速进行数据统计和分析，如年龄分布统计等，这在关系型数据库中可能需要更多的计算资源和时间。 安全性和稳定性：通过配置安全模式的Elasticsearch集群和MySQL数据库，以及使用SSL安全连接，可以保证数据传输的安全性和系统的稳定性。 易于监控和维护：Elasticsearch提供了丰富的监控工具和API，使得系统维护和性能监控变得更加容易。 扩展性：Elasticsearch集群可以根据业务需求进行水平扩展，增加更多的节点来处理更大的数据量和查询负载。 这些优势使得Elasticsearch集群成为关系型数据库在处理全文检索和高并发Ad Hoc查询时的有效补充。

迁移时长 迁移过程的耗时长短依赖于源集群和目标集群的节点个数或索引shard个数。迁移过程分为备份阶段和恢复阶段，备份阶段耗时由源集群决定，恢复阶段耗时由目标集群决定。迁移总时长的评估公式如下： 当索引shard个数大于节点个数时 总时长（s）= 集群迁移的数据量（GB）÷ 40MB ÷（源集群节点个数+目的集群节点个数）x 索引个数 当索引shard个数小于节点个数时 总时长（s）= 集群迁移的数据量（GB）÷ 40MB ÷（源集群索引shard个数+目的集群索引shard个数）x 索引个数 评估公式是基于理想状态下（即单节点以最快速度40MB/s传输）的迁移时长，实际迁移时长还会受到网络、资源等因素影响。

应用场景 通过备份与恢复实现华为云Elasticsearch集群间数据迁移仅适用于源集群和目标集群都是 CSS 服务的集群，且依赖 对象存储服务 OBS。常用于以下场景： 跨地域或跨账号迁移：将其他Region或账号下的Elasticsearch集群迁移到当前集群中。 跨版本迁移：将低版本的Elasticsearch集群数据迁移到高版本的集群中。 集群合并：将两个Elasticsearch集群的索引数据合并到一个集群中。

方案优势 易于操作和管理：在 CS S服务控制台使用集群快照功能实现备份恢复，操作简单，且易于管理和自动化。 适用于大规模数据迁移：快照备份适用于数据量大的场景，特别是当数据量达到GB、TB甚至PB级别时。 支持跨地域和跨账号迁移：通过结合OBS的跨区域复制功能，可以实现跨地域和跨账号的数据迁移。 恢复过程可控：在恢复数据时，可以选择恢复特定索引或全部索引，并且可以指定恢复到特定的集群状态。 迁移时长可控：基于迁移时长评估公式可以配置数据迁移速率，理想状态下等于文件复制速率。

步骤四：创建知识库 如果需要基于知识库进行智能问答，则需要在Dify平台配置知识库。 在Dify平台上方选择“知识库”。 单击“创建知识库”。 选择“导入已有文本”，上传文本文件。 单击“下一步”，根据业务需要设置知识库，其中Embedding模型和Rerank模型选择1接入的模型。 图8 设置知识库 单击“保存并处理”，等待知识库嵌入完成。此时，文本文件就通过Dify平台调用Embedding搜索大模型写入了OpenSearch向量数据库。 单击“前往文档”，进入知识库。 单击左侧“召回测试”，验证是否可以正常召回文本内容。 如图9所示，回答正确，表示文档召回成功。 图9 召回测试

步骤五：创建智能问答助手 在Dify平台创建聊天助手，并进行调试预览，验证AI应用是否能够正常运行。 在Dify平台上方选择“工作室”。 单击“创建空白应用”，配置应用信息。“选择应用类型”必须选择“聊天助手”，“应用名称”可以自定义，例如test。 单击“创建”，进入应用编排页面。 在编排页面右侧，确认应用已关联DeepSeek模型服务。 图10 确认模型 在编排页面调试智能问答助手，验证功能。 智能问答助手支持2种调试方式：直接问答和知识增强问答。 直接问答：聊天助手不对接知识库，直接调用DeepSeek模型生成问答。 该方式无需配置“上下文”，智能问答助手会直接使用DeepSeek回答问题，如图11所示。 图11 直接大模型问答 知识增强问答：聊天助手对接知识库，并基于知识库内容，结合DeepSeek模型输出精准答案。 该方式需要先在“上下文”添加步骤四：创建知识库创建的知识库，再进行问答，为了突出和大模型回答的差异，可以在“提示词”添加内容“仅根据上下文进行回答”，智能问答助手就会优先根据知识库的文档进行回答，如图12所示。 图12 结合知识库问答

步骤三：Dify接入Embedding和DeepSeek Dify作为一个开源的大语言模型（LLM）应用开发平台，通过配置和调用搜索大模型和DeepSeek模型服务的API，来实现功能集成和扩展。 在Dify平台接入搜索大模型，包含Embedding模型和Rerank模型。 单击Dify平台右上角的头像，选择“设置”中的“模型供应商”。 在模型供应商页面中选择“OpenAI-API-compatible”，单击“添加模型”配置Embedding和Rerank模型。配置说明参见表1。 表1 添加搜索大模型 参数名称 Embedding参数值 Rerank参数值 模型类型 选择“Text Embedding”。 选择“Rerank”。 模型名称 填写“query2doc”。 填写“rerank”。 API endpoint URL 填写“http://{搜索大模型的内网访问地址}/v1”，搜索大模型的内网访问地址即为2获取的IP地址和端口号。例如获取到的内网地址为“xx.xx.xx.xx:xxxx”，则此处填写“http://xx.xx.xx.xx:xxxx/v1”。 模型上下文长度 填写“512”。Embedding搜索大模型只支持512。 “OpenAI-API-compatible”模板会对Rerank分数做归一化，这个并不影响最终结果排序，但是如果需要使用分值过滤，则建议使用“Xorbits Inference”模板配置Rerank模型，配置说明参见表2。 表2 添加Rerank模型 参数名称 参数值 模型类型 选择“Rerank”。 模型名称 填写“rerank”。 服务器URL 填写“http://{搜索大模型的内网访问地址}”，搜索大模型的内网访问地址即为2获取的IP地址和端口号。例如获取到的内网地址为“xx.xx.xx.xx:xxxx”，则此处填写“http://xx.xx.xx.xx:xxxx”。 模型UID 填写“rerank”。 在模型列表可以查看接入的模型。 图6 查看接入的模型 在Dify平台接入DeepSeek模型服务。 单击Dify平台右上角的头像，选择“设置”中的“模型供应商”。 在模型供应商页面中选择“OpenAI-API-compatible”，单击“添加模型”配置DeepSeek信息。配置说明参见表3。 表3 添加DeepSeek 参数名称 参数值 模型类型 选择“LLM”。 模型名称 填写DeepSeek模型服务的模型名称，即3获取的模型名称。 API Key 填写DeepSeek模型服务的API Key，即3获取的API Key。 API endpoint URL 填写DeepSeek模型服务的Open API地址，即3获取的API地址。 最大token上限 填写“1024”。DeepSeek模型服务只支持1024。 在模型列表可以查看接入的模型。 图7 查看接入的DeepSeek

应用场景 基于开源框架Dify构建，打造具备双重能力的智能对话助手。系统支持用户自由选择直接调用DeepSeek大模型进行开放式问答，或结合企业私有知识库实现精准信息检索与推理应答，适用于智能客服、知识库问答、个性化推荐等多种业务场景。通过OpenSearch向量数据库实现毫秒级语义检索，配合CSS搜索大模型的Embedding向量化与Rerank重排序技术，可精准匹配海量非结构化数据。独享版大模型服务保障企业数据隔离与模型性能稳定，MaaS平台提供的DeepSeek模型则赋予系统强大的上下文理解和多轮对话能力。

方案优势 该方案适合需要快速构建企业级知识中枢、同时兼顾通用对话能力、创新效率与成本控制的场景，具备以下核心优势： 灵活架构支持知识问答与开放对话模式自由切换，适应多样化业务需求。 私有化部署保障数据安全，满足金融、医疗等敏感行业合规要求。 检索增强生成（RAG）技术有效解决大模型幻觉问题，提升回答准确性与可信度。 开箱即用的可视化配置界面，显著降低AI应用开发门槛，企业可快速完成从数据接入到智能服务上线的全流程。

步骤二：部署Dify 在服务器上部署Dify容器，并接入OpenSearch向量数据库。本案例以弹性 云服务器ECS 为例介绍操作步骤。Dify的详细安装指导请参见Docker Compose部署。 参考快速购买和使用Linux ECS，购买ECS。 ECS的实例规则要大于或等于2U4G，虚拟私有云要和OpenSearch的VPC一致，并且必须绑定弹性公网IP。 参考手工部署Docker，在ECS实例上安装Docker。 克隆Dify的源代码到ECS实例上，并切换至某tag版本分支，以0.15.3版本为例。 git clone https://github.com/langgenius/dify.git && cd dify git checkout -b 0.15.3 0.15.3 进入Dify源代码的Docker目录，修改“.env”文件，配置OpenSearch向量数据库的信息。 进入docker目录，复制生成“.env”文件，并进入编辑。 cd docker && cp .env.example .env vim .env 修改VECTOR_STORE参数值，改为opensearch。 VECTOR_STORE=opensearch 修改OpenSearch向量数据库的信息，改为1获取的信息。 OPENSEARCH_HOST=x.x.x.x # OpenSearch的访问地址（IP地址） OPENSEARCH_PORT=9200 # OpenSearch的端口号 OPENSEARCH_USER=admin # OpenSearch的访问账号（非安全集群直接删除） OPENSEARCH_PASSWORD=******* # OpenSearch的访问密码（非安全集群直接删除） OPENSEARCH_SECURE=true # 如果Opensearch为安全集群则将该配置设置为true 保存修改。 执行命令，启动Dify容器。 docker compose up -d 执行命令，确认容器是否启动成功。 docker ps 显示如下信息表示启动成功。 图5 查看Dify容器 通过ECS的弹性公网IP访问部署在ECS上的Dify平台。 在浏览器输入“http://{ECS公网IP}:80”访问Dify的开发平台。首次登录需注册管理员账号，依次填写邮箱、账号、密码。

应用场景 Elasticsearch是一个高度可扩展的开源搜索和分析引擎，支持用户通过自定义规则对搜索结果进行排序。自定义排序允许开发者根据业务需求，定义特定的排序规则，以优化搜索结果的相关性和用户体验。该方案可以用于以下场景： 电子商务：根据销量、用户评价、价格等因素对商品进行排序。 内容管理：根据阅读量、发布时间对文章或博客帖子进行排序。 金融服务：根据交易金额、频率或风险评分对交易记录进行排序。 客户支持：根据工单的紧急程度或打开时间对客户请求进行排序。

方案架构 通过自定义规则对搜索结果进行排序是通过Elasticsearch的排序API实现的。通过调用排序API查询数据，实现数据按自定义规则排序。 自定义规则查询有两种方式。 用绝对好评率计算总分，按照总分由高到低的顺序排列出查询结果。 总分 = 匹配得分 * （好评率 * 绝对因子） 匹配得分：根据查询结果计分，内容匹配记1分，否则记0分，得分之和即为匹配得分。 好评率：从匹配项的数据内容中获取好评率的值，一般指单条数据的评分。 绝对因子：自定义的好评比例。 用相对好评率计算总分，按照总分由高到低的顺序排列查询结果。 总分 = 匹配得分 * （好评率 * 相对分数） 匹配得分：根据查询结果计分，内容匹配记1分，否则记0分，得分之和即为匹配得分。 好评率：从匹配项的数据内容中获取好评率的值，一般指单条数据的评分。 相对分数：自定义一个好评率阈值，当好评率大于阈值时，返回一个自定义的相对分数；当好评率小于等于阈值时，返回另一个自定义的相对分数。通过这种方式可以避免异常好评率对查询结果的影响。

脚本“perf.lua” local random = math.random local reqs = {} local cnt = 0 -- 压测的查询请求文件名称根据需要调整。 for line in io.lines("requests.txt") do table.insert(reqs, line) cnt = cnt + 1 end local addrs = {} local counter = 0 function setup(thread) local append = function(host, port) for i, addr in ipairs(wrk.lookup(host, port)) do if wrk.connect(addr) then addrs[#addrs+1] = addr end end end if #addrs == 0 then -- 根据集群的实际地址进行修改。 append("x.x.x.x", 9200) append("x.x.x.x", 9200) append("x.x.x.x", 9200) end local index = counter % #addrs + 1 counter = counter + 1 thread.addr = addrs[index] end -- 索引名称根据需要调整。 wrk.path = "/index_sift_graph/_search?request_cache=false&preference=_local" wrk.method = "GET" wrk.headers["Content-Type"] = "application/json" function request() return wrk.format(wrk.method, wrk.path, wrk.headers, reqs[random(cnt)]) end

脚本“base_test_example.py” # -*- coding: UTF-8 -*- import json import time import h5py from elasticsearch import Elasticsearch from elasticsearch import helpers def get_client(hosts: list, user: str = None, password: str = None): if user and password: return Elasticsearch(hosts, http_auth=(user, password), verify_certs=False, ssl_show_warn=False) else: return Elasticsearch(hosts) # 索引参数说明请参见在Elasticsearch集群创建向量索引。 def create(es_client, index_name, shards, replicas, dim, algorithm="GRAPH", metric="euclidean", neighbors=64, efc=200, shrink=1.0): index_mapping = { "settings": { "index": { "vector": True }, "number_of_shards": shards, "number_of_replicas": replicas, }, "mappings": { "properties": { "id": { "type": "integer" }, "vec": { "type": "vector", "indexing": True, "dimension": dim, "algorithm": algorithm, "metric": metric, "neighbors": neighbors, "efc": efc, "shrink": shrink, } } } } es_client.indices.create(index=index_name, body=index_mapping) print(f"Create index success! Index name: {index_name}") def write(es_client, index_name, vectors, bulk_size=1000): print("Start write! Index name: " + index_name) start = time.time() for i in range(0, len(vectors), bulk_size): actions = [{ "_index": index_name, "id": i + j, "vec": v.tolist() } for j, v in enumerate(vectors[i: i + bulk_size])] helpers.bulk(es_client, actions, request_timeout=180) print(f"Write success! Docs count: {len(vectors)}, total cost: {time.time() - start:.2f} seconds") merge(es_client, index_name) def merge(es_client, index_name, seg_cnt=1): print(f"Start merge! Index name: {index_name}") start = time.time() es_client.indices.forcemerge(index=index_name, max_num_segments=seg_cnt, request_timeout=7200) print(f"Merge success! Total cost: {time.time() - start:.2f} seconds") # 查询参数说明请参考见在Elasticsearch集群使用向量索引搜索数据。 def query(es_client, index_name, queries, gts, size=10, k=10, ef=200, msn=10000): print("Start query! Index name: " + index_name) i = 0 precision = [] for vec in queries: hits = set() dsl = { "size": size, "stored_fields": ["_none_"], "docvalue_fields": ["id"], "query": { "vector": { "vec": { "vector": vec.tolist(), "topk": k, "ef": ef, "max_scan_num": msn } } } } res = es_client.search(index=index_name, body=json.dumps(dsl)) for hit in res['hits']['hits']: hits.add(int(hit['fields']['id'][0])) precision.append(len(hits.intersection(set(gts[i, :size]))) / size) i += 1 print(f"Query complete! Average precision: {sum(precision) / len(precision)}") def load_test_data(src): hdf5_file = h5py.File(src, "r") base_vectors = hdf5_file["train"] query_vectors = hdf5_file["test"] ground_truths = hdf5_file["neighbors"] return base_vectors, query_vectors, ground_truths def test_sift(es_client): index_name = "index_sift_graph" vectors, queries, gts = load_test_data(r"sift-128-euclidean.hdf5") # 根据实际测试需求调整分片和副本数、索引算法、索引参数等。本文性能测试均配置的是1个分片、2个副本。 create(es_client, index_name, shards=1, replicas=2, dim=128) write(es_client, index_name, vectors) query(es_client, index_name, queries, gts) if __name__ == "__main__": # 此处修改为CSS集群的实际访问地址。 client = get_client(['http://x.x.x.x:9200']) test_sift(client)

性能测试的操作步骤 创建一个弹性云服务器ECS，用于安装压测工具和执行测试脚本。操作指导请参见快速购买和使用Linux ECS。 ECS必须和Elasticsearch集群在同一个虚拟私有云和安全组中。 也可以使用其他客户端服务器，但是必须保证服务器和Elasticsearch集群在同一VPC。 将测试数据集上传到ECS上。 将数据写入和召回率测试脚本上传到ECS上，并执行如下命令。 pip install h5py pip install elasticsearch==7.6 python3 base_test_example.py 执行完成后，会创建测试的向量索引，写入测试数据，并返回平均查询召回率Recall。 在ECS上安装开源压测工具Wrk。 在ECS上准备压测的查询请求文件，用于模拟真实业务场景。参考脚本prepare_query.py。 pip install h5py python3 prepare_query.py 在ECS上准备Wrk的压测配置脚本。参考脚本perf.lua，脚本中的查询请求文件名称、集群访问地址和索引名称需要根据实际环境修改。 在ECS执行如下命令进行向量检索的性能压测。 wrk -c60 -t60 -d10m -s perf.lua http://x.x.x.x:9200 “t”表示压测线程数。 “c”表示与服务端的连接数。 “d”表示压测时间，“10m”表示10分钟 。 “s”表示Wrk的压测配置脚本。 “x.x.x.x”表示Elasticsearch集群的访问地址。 在回显中获得测试数据，其中“Requests/sec”即查询吞吐量QPS。 图2 测试结果示例

性能测试比较 以下测试方案只列出了对比项的参数值，未列举的参数建议保持默认值。 GRAPH类索引 百万规模的场景推荐使用GRAPH索引类型。 测试方案一：使用不同维度的数据集，在Top10召回率均达到99%的情况下，测试向量数据库能支撑的最大QPS。每个数据集均基于默认参数和调优参数分别进行测试，通过调整构建参数可以使得图索引结构更优，在同等召回精度下能取得更高的查询性能。 测试结果： 表1 GRAPH类索引测试结果1 数据集 构建参数 查询参数 性能指标 efc shrink ef max_scan_num QPS Recall sift-128-euclidean 200 1.0 84 10000 15562 0.99 500 0.8 50 10000 17332 0.99 cohere-768-cosine 200 1.0 154 10000 3232 0.99 500 0.95 106 10000 3821 0.99 gist-960-euclidean 200 1.0 800 19000 860 0.99 500 0.9 400 15000 1236 0.99 结论：对于不同的数据集，使用默认参数均能达到99%以上的召回率。在进一步调整构建参数和查询参数后，增加了一定的索引构建开销，同时也达到更高的查询性能。 测试方案二：使用同一数据集，通过调整索引参数，测试不同召回率下的查询性能。本方案用COHERE数据集，分别测试了Top10召回率为99%、98%及95%时的集群最大QPS。 测试结果： 表2 GRAPH类索引测试结果1 数据集 构建参数 查询参数 性能指标 efc ef QPS Recall cohere-768-cosine 500 128 3687 0.99 500 80 5320 0.98 500 36 9028 0.95 结论：同一集群在统一索引构建参数的情况下，通过调整ef参数可以获得不同的查询精度，在略微损失召回率的场景下可以获得成倍的性能提升。 GRAPH_PQ类索引 基于图算法的索引为了保证查询性能通常需要常驻内存，因此当向量维度较高或数据量较大时，内存资源成为影响成本及性能的关键因素。具体来说，高维度的向量和大规模的数据集对内存的需求显著增加，这不仅关系到存储成本，还直接影响到索引算法的运行效率和响应速度。该场景推荐使用GRAPH_PQ索引类型。 测试方案：使用维度较高的COHERE与GIST数据集，测试在Top10召回率达到95%时的集群最大QPS，并与GRAPH索引对比常驻内存开销。 测试结果： 表3 GRAPH_PQ类索引测试结果 数据集 构建参数 查询参数 性能指标 内存开销 efc fragment_num ef topk QPS Recall GRAPH_PQ GRAPH cohere-768-cosine 200 64 85 130 8723 0.95 332MB 3.3GB gist-960-euclidean 200 120 200 360 4267 0.95 387MB 4.0GB 结论：结果显示使用GRAPH_PQ类索引能够在节约10倍+内存开销的情况下，取得与GRAPH索引差不多的精度和性能。因此，CSS向量索引的GRAPH_PQ算法融合了图索引与量化算法，能够大幅降低内存的开销，提升单机的数据容量。 测试数据中涉及的索引参数说明请参见表4，关于构建参数的详细说明请参见在Elasticsearch集群创建向量索引，关于查询参数的详细说明请参见在Elasticsearch集群使用向量索引搜索数据。 表4 索引参数说明 类型 参数名称 说明 构建参数 efc 构建hnsw时考察邻居节点的队列大小，默认值为200，值越大精度越高，构建速度将会变慢。 shrink 构建hnsw时的裁边系数，默认值为1.0f。 fragment_num 段数，默认值为0，插件自动根据向量长度设置合适的段数。 查询参数 ef 查询时考察邻居节点的队列大小。值越大查询精度越高，查询速度会变慢。默认值为200。 max_scan_num 扫描节点上限。值越大精度越高，查询速度变慢。默认值为10000。 topk 查询时返回top k条数据。