尧图网页设计 
Higress AI 意图识别插件ai-intent实战指南基于 LLM 的请求意图分类与路由决策【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress导读ai-intent 是 Higress 提供的一款 AI 原生网关插件它在大模型请求进入主链路之前先调用一次 LLM 对用户提问做意图分类再把识别出的类别写入 Wasm Property键为intent_category供后续 ai-proxy、ai-cache 等插件按意图做路由、缓存或模型选择。本文以仓库中的 plugins/wasm-rust/example/ai-intent/README.md 为骨架结合 Rust 示例实现src/lib.rs与 Go 正式实现plugins/wasm-go/extensions/ai-intent/main.go及单元测试完整讲解插件的工作原理、前置依赖、全部配置参数与可复制的配置示例。功能说明什么是 AI 意图识别ai-intent 插件通过 LLM大语言模型智能判断用户请求与某个领域或 agent 的功能契合度从而提升不同模型的应用效果和用户体验。简单来说它把这条请求属于哪个业务场景这个问题交给大模型回答再以结构化的结果暴露给网关内其他插件使用。典型应用场景包括按意图路由识别出请求属于金融 / 电商 / 法律让 ai-proxy 把请求转发给对应领域更擅长的大模型按意图选择缓存策略识别出时效性敏感的请求如实时行情、新闻快讯关闭 ai-cache 缓存保证数据新鲜度按意图做模型选择不同类别的请求走不同模型、不同配置实现多模型的分流治理。从源码结构看该插件存在两个实现一个位于 plugins/wasm-rust/example/ai-intentRust 示例AiIntentRoot/AiIntent结构体另一个位于 plugins/wasm-go/extensions/ai-intentGo 正式实现PluginConfig结构体。二者配置结构基本一致本文以 Rust 示例文档为骨架结合两份源码共同印证。运行属性插件执行阶段默认阶段插件执行优先级700在 Higress 的 Wasm 插件模型中执行优先级数值越大越先执行。ai-intent 以700的优先级先于 ai-proxy 等后续消费意图的插件运行确保意图结果在链路下游被读取时已经就绪。Go 实现中标注的执行阶段为AUTHN、优先级为1000见 main.go 顶部的Phase AUTHN/Priority 1000元数据不同实现优先级存在差异部署时以实际产物为准但核心原则一致意图识别必须先于意图消费执行。工作原理从请求体到意图 Property结合 Rust 源码 src/lib.rs 与 Go 源码 main.go插件的工作流程可以拆解为四个阶段拦截请求体在on_http_request_headers中检测到存在请求体时返回HeaderAction::StopIteration随后在on_http_request_complete_body中拿到完整请求体Rust 端通过cache_request_body() - true开启缓存。提取用户问题按keyFrom.requestBody配置的 JSONPath 从请求体中提取原始问题文本。Rust 默认路径为$.messages[0].contentGo 默认路径为messages.reverse.0.content取最后一条 user 消息。调用 LLM 做分类插件将用户问题 预设类别填入 prompt 模板构造 OpenAI 协议格式的请求modelmessages通过http_call/ProxyClient.Post异步调用llm.proxyUrl指向的大模型路由并设置Authorization: Bearer proxyApiKey头超时时间由llm.proxyTimeout控制。解析结果并写 PropertyLLM 返回200后按keyFrom.responseBody提取分类结果Rust 默认$.choices[0].message.contentGo 默认choices.0.message.content解析为意图键值对并通过set_property(vec![intent_category:xxx], ...)Rust或proxywasm.SetProperty([]string{intent_category}, ...)Go写入属性随后resume_http_request()放行原请求。Rust 端支持一次返回多个场景的意图LLM 返回的每一行{use_for:scene1,result:result1}会被解析为独立的 Property键形如intent_category:use_for如果 LLM 返回了非结构化文本插件还会退化为在文本中按use_for与options做包含匹配尽力兜底解析message_to_intent_res函数。下游消费方式后续插件可通过proxywasm.GetProperty([]string{intent_category})或带场景名的intent_category:xxx获取意图主题据此选择不同的缓存库或大模型。这一契约在 main_test.go 中有完整的单测验证模拟请求体今天股市怎么样返回金融、模拟这个商品什么时候发货返回电商、模拟无关问题则不设置 Property并通过host.GetProperty([]string{intent_category})断言结果。前置依赖务必按顺序完成原文档明确给出 4 项前置条件缺一不可优先级要求该插件优先级高于 ai-proxy 等后续使用意图的插件保证intent_category在链路下游可读。新建大模型路由需新建一条 Higress 大模型路由供本插件访问大模型。例如路由以/intent作为前缀服务选择大模型服务并为该路由开启 ai-proxy 插件。路由地址形如http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions。新建固定地址服务需新建一个固定地址的服务如intent-service服务指向127.0.0.1:80即自身网关实例 端口ai-intent 插件内部通过该服务回环调用上一步的路由。服务名对应llm.proxyServiceName取 Higress 中的 FQDN 值示例中为intent-service.static也可以新建 DNS 类型服务使插件直接访问其他外部大模型。添加访问白名单如果使用固定地址服务调用网关自身需把127.0.0.1加入网关的访问白名单否则回环调用会被网关拦截。配置参数详解以下参数表完整继承自原文档并结合源码补充了默认值与解析逻辑Rust 示例实现以scene.categories[].use_for形式组织场景Go 正式实现使用scene.category的|分隔字符串二选一即可名称数据类型填写要求默认值描述scene.categories[].use_forstring必填-场景用途标识LLM 返回的意图将挂在intent_category:use_for下Rust 实现scene.categories[].optionsarray of string必填-该场景下的预设类别候选值Rust 实现scene.categorystring必填-预设场景类别以\|分割如金融\|电商\|法律\|HigressGo 实现scene.promptstring非必填见下方默认 Promptllm 请求 prompt 模板Rust 端内置${question}、${categories}两个占位符llm.proxyServiceNamestring必填-新建的 Higress 服务指向大模型取 Higress 中的 FQDN 值如intent-service.staticllm.proxyUrlstring必填-大模型路由请求地址全路径可以是网关自身地址也可以是其他大模型地址OpenAI 协议例如http://127.0.0.1:80/intent/compatible-mode/v1/chat/completionsllm.proxyDomainstring非必填从 proxyUrl 中解析获取大模型服务的 domainllm.proxyPortnumber非必填从 proxyUrl 中解析获取大模型服务端口号llm.proxyApiKeystring非必填-当使用外部大模型服务时需配置对应大模型的 API_KEYllm.proxyModelstring非必填qwen-long大模型类型llm.proxyTimeoutnumber非必填10000调用大模型超时时间单位 ms默认 10000ms默认 Prompt 模板Rust 实现见 src/lib.rsYou are an intelligent category recognition assistant, responsible for determining which preset category a question belongs to based on the users query and predefined categories, and providing the corresponding category. The users question is: ${question} The preset categories are: ${categories} Please respond directly with the category in the following manner: [ {use_for:scene1,result:result1}, {use_for:scene2,result:result2} ] Ensure that different use_for are on different lines, and that use_for and result appear on the same line.Go 实现的默认 Prompt 为中文你是一个智能类别识别助手负责根据用户提出的问题和预设的类别确定问题属于哪个预设的类别并给出相应的类别……直接返回一种具体类别如果没有找到就返回NotFound。 两份默认模板都要求 LLM 以固定格式返回类别便于插件做结构化解析。解析细节源码佐证proxyDomain未配置时从proxyUrl解析 hostproxyPort未配置时从proxyUrl解析端口解析不到时 HTTP 默认80、HTTPS 默认443见 main.goproxyModel为空时回退为qwen-longproxyTimeout为 0 时回退为10000ms见 src/lib.rs插件通过FQDNCluster::new(proxyServiceName, proxyDomain, proxyPort)构造上游集群即以配置的 FQDN 服务名发起回环或外部调用。完整配置示例以下 YAML 完整取自原文档Rust 示例实现可直接复制并按需修改scene: category: - use_for: intent-route options: - Finance - E-commerce - Law - Others - use_for: disable-cache options: - Time-sensitive - An innovative response is needed - Others llm: proxy_service_name: intent-service.static proxy_url: http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions proxy_domain: 127.0.0.1 proxy_port: 80 proxy_model: qwen-long proxy_api_key: proxy_timeout: 10000该示例定义了 2 个意图场景intent-route意图路由候选类别为 Finance、E-commerce、Law、Others下游 ai-proxy 可据此把请求分发到不同模型disable-cache关闭缓存候选类别为 Time-sensitive时效性敏感、An innovative response is needed需要创新性回答、Others下游 ai-cache 可据此跳过缓存保证时效性。LLM 部分指向网关自身的/intent路由intent-service.static固定地址服务 127.0.0.1:80使用qwen-long模型10 秒超时若直连外部大模型OpenAI 协议需同时配置proxy_api_key。Go 正式实现的等价格式为scene.category字符串拼接见 main.go 的示例注释与 plugins/wasm-go/extensions/ai-intent/README.mdscene: category: 金融|电商|法律|Higress prompt: 你是一个智能类别识别助手负责根据用户提出的问题和预设的类别确定问题属于哪个预设的类别并给出相应的类别。用户提出的问题为:%s,预设的类别为%s直接返回一种具体类别如果没有找到就返回NotFound。 llm: proxyServiceName: intent-service.static proxyUrl: http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions proxyDomain: 127.0.0.1 proxyPort: 80 proxyModel: qwen-long proxyApiKey: proxyTimeout: 10000场景联动示例意图感知的缓存与路由ai-intent 的价值在于与下游插件联动。结合配置示例一个典型的意图感知链路如下ai-intent优先级 700在请求体阶段完成 LLM 分类写入intent_category:intent-routeFinance、intent_category:disable-cacheTime-sensitive等 Propertyai-proxy 在后续阶段读取intent_category将金融类请求路由到金融领域模型ai-cache 读取intent_category:disable-cache对时效性敏感请求跳过缓存保障数据新鲜度。这种先识别、后决策的模式避免了为每个业务场景单独编写规则把类别判断的灵活性交给 LLM让网关策略具备语义理解能力。测试与验证仓库为该插件提供了完整的单元测试支撑Rust 端在 src/lib.rs 内置test_message_to_intent_res用例覆盖 LLM 返回 JSON 行格式、带 json 包裹、带多余空格与空行、单引号变体、以及 LLM 拒绝回答等异常场景验证message_to_intent_res的解析与兜底逻辑Go 端在 main_test.go 中通过模拟 LLM HTTP 响应断言intent_categoryProperty 被正确写入金融电商等类别未命中时 Property 保持为空。这些测试同时给出了 LLM 返回格式的标准答案可作为调试插件时构造 mock 响应的参考。小结与最佳实践回环还是直连优先按文档示例使用固定地址服务回环调用网关自身注意白名单便于复用网关上的鉴权、限流与 ai-proxy 能力直连外部大模型时务必配置proxyApiKey并确保proxyUrl遵循 OpenAI 协议。意图场景命名use_for建议用语义清晰的标识如intent-route、disable-cache与下游插件的读取逻辑一一对应。超时与降级proxyTimeout默认 10s可根据 LLM 实际延迟调整当 LLM 调用失败或返回非 200 时插件直接放行原请求resume_http_request不会阻塞主链路属于识别失败则跳过的安全降级设计。结合源码深入Rust 实现见 plugins/wasm-rust/example/ai-intent/src/lib.rsGo 正式实现见 plugins/wasm-go/extensions/ai-intent/main.go其依赖的 Wasm Rust SDK 位于 plugins/wasm-rust 目录构建方式可参考 plugins/wasm-rust/README.md。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Higress AI 意图识别插件（ai-intent）实战指南：基于 LLM 的请求意图分类与路由决策
Higress AI 意图识别插件ai-intent实战指南基于 LLM 的请求意图分类与路由决策【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress导读ai-intent 是 Higress 提供的一款 AI 原生网关插件它在大模型请求进入主链路之前先调用一次 LLM 对用户提问做意图分类再把识别出的类别写入 Wasm Property键为intent_category供后续 ai-proxy、ai-cache 等插件按意图做路由、缓存或模型选择。本文以仓库中的 plugins/wasm-rust/example/ai-intent/README.md 为骨架结合 Rust 示例实现src/lib.rs与 Go 正式实现plugins/wasm-go/extensions/ai-intent/main.go及单元测试完整讲解插件的工作原理、前置依赖、全部配置参数与可复制的配置示例。功能说明什么是 AI 意图识别ai-intent 插件通过 LLM大语言模型智能判断用户请求与某个领域或 agent 的功能契合度从而提升不同模型的应用效果和用户体验。简单来说它把这条请求属于哪个业务场景这个问题交给大模型回答再以结构化的结果暴露给网关内其他插件使用。典型应用场景包括按意图路由识别出请求属于金融 / 电商 / 法律让 ai-proxy 把请求转发给对应领域更擅长的大模型按意图选择缓存策略识别出时效性敏感的请求如实时行情、新闻快讯关闭 ai-cache 缓存保证数据新鲜度按意图做模型选择不同类别的请求走不同模型、不同配置实现多模型的分流治理。从源码结构看该插件存在两个实现一个位于 plugins/wasm-rust/example/ai-intentRust 示例AiIntentRoot/AiIntent结构体另一个位于 plugins/wasm-go/extensions/ai-intentGo 正式实现PluginConfig结构体。二者配置结构基本一致本文以 Rust 示例文档为骨架结合两份源码共同印证。运行属性插件执行阶段默认阶段插件执行优先级700在 Higress 的 Wasm 插件模型中执行优先级数值越大越先执行。ai-intent 以700的优先级先于 ai-proxy 等后续消费意图的插件运行确保意图结果在链路下游被读取时已经就绪。Go 实现中标注的执行阶段为AUTHN、优先级为1000见 main.go 顶部的Phase AUTHN/Priority 1000元数据不同实现优先级存在差异部署时以实际产物为准但核心原则一致意图识别必须先于意图消费执行。工作原理从请求体到意图 Property结合 Rust 源码 src/lib.rs 与 Go 源码 main.go插件的工作流程可以拆解为四个阶段拦截请求体在on_http_request_headers中检测到存在请求体时返回HeaderAction::StopIteration随后在on_http_request_complete_body中拿到完整请求体Rust 端通过cache_request_body() - true开启缓存。提取用户问题按keyFrom.requestBody配置的 JSONPath 从请求体中提取原始问题文本。Rust 默认路径为$.messages[0].contentGo 默认路径为messages.reverse.0.content取最后一条 user 消息。调用 LLM 做分类插件将用户问题 预设类别填入 prompt 模板构造 OpenAI 协议格式的请求modelmessages通过http_call/ProxyClient.Post异步调用llm.proxyUrl指向的大模型路由并设置Authorization: Bearer proxyApiKey头超时时间由llm.proxyTimeout控制。解析结果并写 PropertyLLM 返回200后按keyFrom.responseBody提取分类结果Rust 默认$.choices[0].message.contentGo 默认choices.0.message.content解析为意图键值对并通过set_property(vec![intent_category:xxx], ...)Rust或proxywasm.SetProperty([]string{intent_category}, ...)Go写入属性随后resume_http_request()放行原请求。Rust 端支持一次返回多个场景的意图LLM 返回的每一行{use_for:scene1,result:result1}会被解析为独立的 Property键形如intent_category:use_for如果 LLM 返回了非结构化文本插件还会退化为在文本中按use_for与options做包含匹配尽力兜底解析message_to_intent_res函数。下游消费方式后续插件可通过proxywasm.GetProperty([]string{intent_category})或带场景名的intent_category:xxx获取意图主题据此选择不同的缓存库或大模型。这一契约在 main_test.go 中有完整的单测验证模拟请求体今天股市怎么样返回金融、模拟这个商品什么时候发货返回电商、模拟无关问题则不设置 Property并通过host.GetProperty([]string{intent_category})断言结果。前置依赖务必按顺序完成原文档明确给出 4 项前置条件缺一不可优先级要求该插件优先级高于 ai-proxy 等后续使用意图的插件保证intent_category在链路下游可读。新建大模型路由需新建一条 Higress 大模型路由供本插件访问大模型。例如路由以/intent作为前缀服务选择大模型服务并为该路由开启 ai-proxy 插件。路由地址形如http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions。新建固定地址服务需新建一个固定地址的服务如intent-service服务指向127.0.0.1:80即自身网关实例 端口ai-intent 插件内部通过该服务回环调用上一步的路由。服务名对应llm.proxyServiceName取 Higress 中的 FQDN 值示例中为intent-service.static也可以新建 DNS 类型服务使插件直接访问其他外部大模型。添加访问白名单如果使用固定地址服务调用网关自身需把127.0.0.1加入网关的访问白名单否则回环调用会被网关拦截。配置参数详解以下参数表完整继承自原文档并结合源码补充了默认值与解析逻辑Rust 示例实现以scene.categories[].use_for形式组织场景Go 正式实现使用scene.category的|分隔字符串二选一即可名称数据类型填写要求默认值描述scene.categories[].use_forstring必填-场景用途标识LLM 返回的意图将挂在intent_category:use_for下Rust 实现scene.categories[].optionsarray of string必填-该场景下的预设类别候选值Rust 实现scene.categorystring必填-预设场景类别以\|分割如金融\|电商\|法律\|HigressGo 实现scene.promptstring非必填见下方默认 Promptllm 请求 prompt 模板Rust 端内置${question}、${categories}两个占位符llm.proxyServiceNamestring必填-新建的 Higress 服务指向大模型取 Higress 中的 FQDN 值如intent-service.staticllm.proxyUrlstring必填-大模型路由请求地址全路径可以是网关自身地址也可以是其他大模型地址OpenAI 协议例如http://127.0.0.1:80/intent/compatible-mode/v1/chat/completionsllm.proxyDomainstring非必填从 proxyUrl 中解析获取大模型服务的 domainllm.proxyPortnumber非必填从 proxyUrl 中解析获取大模型服务端口号llm.proxyApiKeystring非必填-当使用外部大模型服务时需配置对应大模型的 API_KEYllm.proxyModelstring非必填qwen-long大模型类型llm.proxyTimeoutnumber非必填10000调用大模型超时时间单位 ms默认 10000ms默认 Prompt 模板Rust 实现见 src/lib.rsYou are an intelligent category recognition assistant, responsible for determining which preset category a question belongs to based on the users query and predefined categories, and providing the corresponding category. The users question is: ${question} The preset categories are: ${categories} Please respond directly with the category in the following manner: [ {use_for:scene1,result:result1}, {use_for:scene2,result:result2} ] Ensure that different use_for are on different lines, and that use_for and result appear on the same line.Go 实现的默认 Prompt 为中文你是一个智能类别识别助手负责根据用户提出的问题和预设的类别确定问题属于哪个预设的类别并给出相应的类别……直接返回一种具体类别如果没有找到就返回NotFound。 两份默认模板都要求 LLM 以固定格式返回类别便于插件做结构化解析。解析细节源码佐证proxyDomain未配置时从proxyUrl解析 hostproxyPort未配置时从proxyUrl解析端口解析不到时 HTTP 默认80、HTTPS 默认443见 main.goproxyModel为空时回退为qwen-longproxyTimeout为 0 时回退为10000ms见 src/lib.rs插件通过FQDNCluster::new(proxyServiceName, proxyDomain, proxyPort)构造上游集群即以配置的 FQDN 服务名发起回环或外部调用。完整配置示例以下 YAML 完整取自原文档Rust 示例实现可直接复制并按需修改scene: category: - use_for: intent-route options: - Finance - E-commerce - Law - Others - use_for: disable-cache options: - Time-sensitive - An innovative response is needed - Others llm: proxy_service_name: intent-service.static proxy_url: http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions proxy_domain: 127.0.0.1 proxy_port: 80 proxy_model: qwen-long proxy_api_key: proxy_timeout: 10000该示例定义了 2 个意图场景intent-route意图路由候选类别为 Finance、E-commerce、Law、Others下游 ai-proxy 可据此把请求分发到不同模型disable-cache关闭缓存候选类别为 Time-sensitive时效性敏感、An innovative response is needed需要创新性回答、Others下游 ai-cache 可据此跳过缓存保证时效性。LLM 部分指向网关自身的/intent路由intent-service.static固定地址服务 127.0.0.1:80使用qwen-long模型10 秒超时若直连外部大模型OpenAI 协议需同时配置proxy_api_key。Go 正式实现的等价格式为scene.category字符串拼接见 main.go 的示例注释与 plugins/wasm-go/extensions/ai-intent/README.mdscene: category: 金融|电商|法律|Higress prompt: 你是一个智能类别识别助手负责根据用户提出的问题和预设的类别确定问题属于哪个预设的类别并给出相应的类别。用户提出的问题为:%s,预设的类别为%s直接返回一种具体类别如果没有找到就返回NotFound。 llm: proxyServiceName: intent-service.static proxyUrl: http://127.0.0.1:80/intent/compatible-mode/v1/chat/completions proxyDomain: 127.0.0.1 proxyPort: 80 proxyModel: qwen-long proxyApiKey: proxyTimeout: 10000场景联动示例意图感知的缓存与路由ai-intent 的价值在于与下游插件联动。结合配置示例一个典型的意图感知链路如下ai-intent优先级 700在请求体阶段完成 LLM 分类写入intent_category:intent-routeFinance、intent_category:disable-cacheTime-sensitive等 Propertyai-proxy 在后续阶段读取intent_category将金融类请求路由到金融领域模型ai-cache 读取intent_category:disable-cache对时效性敏感请求跳过缓存保障数据新鲜度。这种先识别、后决策的模式避免了为每个业务场景单独编写规则把类别判断的灵活性交给 LLM让网关策略具备语义理解能力。测试与验证仓库为该插件提供了完整的单元测试支撑Rust 端在 src/lib.rs 内置test_message_to_intent_res用例覆盖 LLM 返回 JSON 行格式、带 json 包裹、带多余空格与空行、单引号变体、以及 LLM 拒绝回答等异常场景验证message_to_intent_res的解析与兜底逻辑Go 端在 main_test.go 中通过模拟 LLM HTTP 响应断言intent_categoryProperty 被正确写入金融电商等类别未命中时 Property 保持为空。这些测试同时给出了 LLM 返回格式的标准答案可作为调试插件时构造 mock 响应的参考。小结与最佳实践回环还是直连优先按文档示例使用固定地址服务回环调用网关自身注意白名单便于复用网关上的鉴权、限流与 ai-proxy 能力直连外部大模型时务必配置proxyApiKey并确保proxyUrl遵循 OpenAI 协议。意图场景命名use_for建议用语义清晰的标识如intent-route、disable-cache与下游插件的读取逻辑一一对应。超时与降级proxyTimeout默认 10s可根据 LLM 实际延迟调整当 LLM 调用失败或返回非 200 时插件直接放行原请求resume_http_request不会阻塞主链路属于识别失败则跳过的安全降级设计。结合源码深入Rust 实现见 plugins/wasm-rust/example/ai-intent/src/lib.rsGo 正式实现见 plugins/wasm-go/extensions/ai-intent/main.go其依赖的 Wasm Rust SDK 位于 plugins/wasm-rust 目录构建方式可参考 plugins/wasm-rust/README.md。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考