AI Gateway on Apache Dubbo

KVCache 卸载与分布式管理调度

Mon, 01 Jan 0001 00:00:00 +0000

AI KVCache 过滤器配置

本文档说明如何在 Dubbo-go-Pixiu 中配置和使用 dgp.filter.ai.kvcache 过滤器。

该过滤器通过对接 vLLM（/tokenize）与 LMCache controller API（/lookup、/pin、/compress、/evict），实现：

cache 感知的路由提示
异步缓存管理动作触发
主请求链路非阻塞

架构与请求链路

dgp.filter.ai.kvcache 是一个 HTTP Decode 过滤器。典型处理流程如下：

读取请求体，提取 model 与 prompt（必要时从 messages 回退提取）。
在 TokenManager 中记录本地热点统计（model + prompt）。
尝试 cache 感知路由：
- 从本地 token cache 获取 token
- 调用 LMCache /lookup
- 把优选端点提示写入上下文（llm_preferred_endpoint_id）
启动异步缓存管理协程（best-effort）：
- 调用 vLLM /tokenize
- 必要时调用 LMCache /lookup
- 按策略执行 compress / pin / evict
立即放行后续过滤器链（主请求不被缓存管理阻塞）。

路由约定（重点）

当前 cache 路由依赖 instance id 对齐：

kvcache 过滤器在上下文写入 llm_preferred_endpoint_id
dgp.filter.llm.proxy 读取该值并按 endpoint.id 选目标实例

因此要生效必须满足：

配置 MCP

Mon, 01 Jan 0001 00:00:00 +0000

MCP (Model Context Protocol) 网关配置

本文档解释了如何在您的网关中配置 MCP (Model Context Protocol) 过滤器，使您能够安全地将后端 HTTP API 暴露为可供 AI Agent 调用的"工具"。

简介

MCP (Model Context Protocol) 是一个智能桥梁，连接 AI Agent 与您现有的后端服务。它将一个简单、统一的协议动态转换为标准的 HTTP 请求，允许 Agent 与您的 API 进行交互，就好像它们是本地函数或工具一样。这种方法简化了 Agent 的开发，并为安全性、控制和可观察性提供了一个中心化的管理点。

设置 MCP 端点主要涉及两个过滤器：

dgp.filter.mcp.mcpserver: 核心的 MCP 服务器过滤器，用于定义服务器的身份并将后端 API 暴露为工具。
dgp.filter.http.auth.mcp: 一个可选但推荐使用的安全过滤器，它使用 OAuth 2.0 和基于 JWT 的授权来保护 MCP 端点。

MCP 服务器过滤器 (`dgp.filter.mcp.mcpserver`) 配置

此过滤器是 MCP 网关的核心。它负责定义哪些工具可用，以及它们如何映射到您的后端 HTTP 服务。

服务器信息 (`server_info`)

server_info 块提供了有关您的 MCP 服务器的元数据，这对于服务发现和诊断非常有用。

server_info:
 name: "MCP OAuth 示例服务器"
 version: "1.0.0"
 description: "一个用于工具演示的受 OAuth 保护的 MCP 服务器"
 instructions: "使用读/写令牌通过 MCP 与模拟服务器 API 进行交互"

name (string): MCP 服务器的显示名称。
version (string): 服务器的版本。
description (string): 服务器用途的简要描述。
instructions (string): 为客户端或开发者提供的关于如何与暴露的工具进行交互的说明。

工具配置 (`tools`)

tools 部分是一个数组，其中每个项目定义了 MCP 网关暴露的单个工具。每个工具对应一个特定的后端 HTTP API 端点。

配置上游 endpoint

Mon, 01 Jan 0001 00:00:00 +0000

LLM 网关 endpoint 配置

本文档解释了如何在您的网关路由配置中为大语言模型 (LLM) 配置上游 endpoint。

endpoint 结构

集群中的每个 endpoint 都由一个 id 定义，并且可以包含一个 llm_meta 块用于自定义行为。

clusters:
 - name: "my_llm_cluster"
 endpoints:
 - id: "provider-1-main"
 socket_address:
 domains:
 - api.deepseek.com
 llm_meta:
 # ... 其他特定于 LLM 的配置在此处 ...
 - id: "provider-2-fallback"
 socket_address:
 domains:
 - api.openai.com/v1
 llm_meta:
 # ... 其他特定于 LLM 的配置在此处 ...

`llm_meta` 配置字段

llm_meta 块包含所有与网关应如何处理此 LLM endpoint 相关的特定配置。

fallback

类型: boolean
描述: 决定如果在此endpoint上的所有重试尝试都失败后，网关是否应继续处理集群中的下一个 endpoint。
- true: 如果此endpoint失败，网关将尝试下一个可用的 endpoint。
- false: 如果此endpoint失败，则处理停止，并将最后一个错误返回给客户端。对于 fallback 链中的最后一个 endpoint ，此值应设置为 false。

api_key

注册服务到网关

Mon, 01 Jan 0001 00:00:00 +0000

LLM 服务发现与注册

本文档旨在指导 LLM 服务提供商如何通过 Nacos 注册中心，将其服务实例动态地注册到 LLM 网关。通过遵循这些准则，网关将能够自动发现您的服务，并根据您提供的元数据（metadata）应用相应的路由、重试和 fallback 策略。

注册机制概述

服务发现的核心机制是：您的 LLM 服务作为一个Nacos 实例进行注册，并在注册时提供一组特定的元数据。LLM 网关会监听 Nacos 中的服务变更，读取这些元数据，并将其动态地转换为一个功能齐全的网关 endpoint 配置。

一个基本的 Nacos 注册请求包含以下关键信息：

ServiceName: 您的服务集合的名称 (例如, deepseek-service)。
Ip & Port: 您的服务实例监听流量的网络地址。
Metadata: 一个键值对集合，这是配置所有网关行为的关键。

`metadata` 配置字段

所有网关的特定配置都通过 Nacos 实例的 metadata 字段进行传递。以下是所有支持的 metadata 键及其说明。

cluster

类型: string
必需: 是
描述: 定义此 endpoint 应归属到网关中的哪个集群 (cluster)。网关会根据此值将具有相同 cluster 名称的服务实例聚合在一起。
示例: "deepseek_cluster"

id

类型: string
必需: 是
描述: endpoint 的唯一标识符。它在所属的 cluster 内必须是唯一的。
示例: "deepseek-primary-instance-1"

ip

AI Gateway on Apache Dubbo

KVCache 卸载与分布式管理调度

AI KVCache 过滤器配置

架构与请求链路

路由约定（重点）

配置 MCP

MCP (Model Context Protocol) 网关配置

简介

MCP 服务器过滤器 (dgp.filter.mcp.mcpserver) 配置

服务器信息 (server_info)

工具配置 (tools)

配置上游 endpoint

LLM 网关 endpoint 配置

endpoint 结构

llm_meta 配置字段

注册服务到网关

LLM 服务发现与注册

注册机制概述

metadata 配置字段

MCP 服务器过滤器 (`dgp.filter.mcp.mcpserver`) 配置

服务器信息 (`server_info`)

工具配置 (`tools`)

`llm_meta` 配置字段

`metadata` 配置字段