【高速缓存】 RedisVL MCP 运行指南（下）

9. 连接远程 MCP 客户端

当服务器以 Streamable HTTP 或 SSE 方式运行时，您需要在 MCP 客户端配置中指定服务器 URL。

• Streamable HTTP：http://<host>:<port>/mcp
• SSE：http://<host>:<port>/sse

其中<host>和<port>应与服务器启动参数一致。若服务器绑定0.0.0.0，客户端需使用机器的实际 IP 或域名，并确保该主机名在 Host 白名单中。

示例（Claude Desktop 配置）：

{"mcpServers":{"redisvl":{"url":"http://192.168.1.10:8000/mcp","transport":"streamable-http"}}}

10. 工具合同（Tool Contracts）

RedisVL MCP 向客户端暴露三个核心工具，以下是每个工具的请求/响应格式及行为说明。

10.1list-indexes（发现可用索引）

无参数，返回所有配置的逻辑索引及其元数据。

响应示例：

{"indexes":[{"id":"knowledge","description":"内部运行手册","upsert_available":true,"fields":[{"name":"title","type":"text"},{"name":"category","type":"tag"},{"name":"rating","type":"numeric"}],"limits":{"max_limit":25}}]}

• fields仅列出可用于过滤的字段（标签、数值、地理等），不含向量字段和用于嵌入的文本源字段。
• limits仅显示显式配置的运行时限制（默认值不输出）。
• 底层的 Redis 索引名（redis_name）不会暴露给客户端。

10.2search-records（执行检索）

请求示例（JSON DSL 过滤器）：

{"index":"knowledge","query":"incident response","limit":2,"filter":{"and":[{"field":"category","op":"eq","value":"operations"},{"field":"rating","op":"gte","value":4}]},"return_fields":["title","content"]}

响应示例：

{"index":"knowledge","search_type":"hybrid","offset":0,"limit":2,"results":[{"id":"knowledge:doc-123","score":0.82,"score_type":"hybrid_score","record":{"title":"EU failover runbook","content":"Restore traffic after a regional failover.","category":"operations","rating":5}}]}

• search_type为响应元数据，反映配置的检索类型。
• 返回的record中不包含向量字段（为节约带宽和安全性）。
• 如果请求的offset + limit超出max_result_window，请求会被拒绝。

10.3upsert-records（写入或更新记录）

请求示例：

{"index":"knowledge","records":[{"doc_id":"doc-42","content":"Updated operational guidance","category":"operations","rating":5}],"id_field":"doc_id"}

响应：

{"index":"knowledge","status":"success","keys_upserted":1,"keys":["knowledge:doc-42"]}

• 如果索引配置了vectorizer，且记录中不包含向量字段，服务器会使用default_embed_text_field指定的源字段生成向量。
• 如果记录中已包含向量字段且skip_embedding_if_present为true，则直接写入原向量。
• 若目标索引为只读（全局或单索引），写入请求会被拒绝。

11. 搜索与写入实战示例

11.1 多索引时的发现‑检索流程

在拥有多个索引的服务器上，客户端应首先调用list-indexes获取可用 ID，然后针对特定 ID 执行操作：

// 第一步：列出索引// 请求：list-indexes 无参// 响应中包含 knowledge 和 tickets// 第二步：在 knowledge 中搜索{"index":"knowledge","query":"cache invalidation","limit":3,"return_fields":["title","content"]}

11.2 纯向量检索

当search.type为vector时，只需提供查询文本，服务器会自动向量化并执行 KNN 搜索：

{"query":"cache invalidation incident","limit":3,"return_fields":["title","content"]}

11.3 混合检索（带权重配置）

在配置中设置search.type: hybrid并指定combination_method: LINEAR及linear_text_weight: 0.3，则最终得分 = 0.3文本得分 + 0.7向量得分。客户端请求与向量检索类似，但响应中的score_type会显示hybrid_score。

11.4 过滤器使用

原始字符串过滤器（直接传递 Redis 查询语法）：

{"query":"science","filter":"@category:{science}","return_fields":["content","category"]}

JSON DSL 过滤器（更结构化，支持and/or/not及字段操作）：

{"query":"science","filter":{"and":[{"field":"category","op":"eq","value":"science"},{"field":"rating","op":"gte","value":4}]}}

11.5 分页与字段投影

通过limit和offset实现分页，return_fields精确控制返回内容：

{"query":"science","limit":1,"offset":1,"return_fields":["content","category"]}

12. 写入（Upsert）进阶

12.1 自动生成向量（Server‑side Embedding）

当记录中缺少向量字段时，服务器自动调用配置的向量化器，将default_embed_text_field指定字段的文本转为向量并写入：

{"records":[{"content":"First document","category":"science","rating":5}]}

12.2 使用id_field更新现有文档

若id_field指定的值在 Redis 中已存在，则该记录会被更新；否则创建新文档：

{"records":[{"doc_id":"doc-1","content":"Updated content","category":"engineering"}],"id_field":"doc_id"}

12.3 控制向量重新生成

• skip_embedding_if_present: true（默认）：若记录中已包含vector_field_name字段，则直接使用该向量，不重新生成。
• skip_embedding_if_present: false：无论记录中是否有向量，都强制重新生成（覆盖原有向量）。

通常推荐让服务器管理向量，客户端只需提供源文本，避免传输大型向量。

12.4 纯文本索引的写入

如果索引只配置了全文检索（无vectorizer和vector_field_name），则upsert-records仅写入文本字段，无需关心向量：

{"records":[{"content":"New FAQ entry","category":"support"}]}

13. 故障排查指南

14. 总结

• 配置先行：在启动服务器前，确保所有索引已在 Redis 中创建，且字段名称与配置完全匹配。
• 单索引 vs 多索引：单索引配置最简洁，客户端无需指定index；多索引适合为不同业务场景（如知识库、工单）提供统一接入，但客户端需先调用list-indexes进行发现。
• 安全：生产环境绝对不要使用--allow-unauthenticated绑定到公网接口。请启用 JWT 认证，并通过环境变量或配置文件严格限制 Host/Origin。
• 向量化成本：若向量化服务（如 OpenAI）按量计费，请在runtime中合理设置skip_embedding_if_present避免重复生成，同时限制max_upsert_records防止批量写入产生高昂费用。
• 分页与性能：通过max_result_window限制深度翻页，避免大偏移量查询拖垮 Redis。max_limit和max_upsert_records则防止单次请求数据量过大。

附录：服务器启动流程图

通过以上步骤，能够顺利部署并运行 RedisVL MCP 服务器，将 Redis 的强大检索能力以标准化工具的形式提供给您的智能体或应用。