middleware

package
v1.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatToolsAsXML added in v1.7.1 

func FormatToolsAsXML(tools []types.ToolSchema) string

FormatToolsAsXML 将工具列表转换为 XML 文本描述，注入到 system prompt 中。 LLM 读到这段文本后会按约定的 <tool_calls> 格式输出工具调用。

func ParseXMLToolCalls added in v1.7.1 

func ParseXMLToolCalls(content string) ([]types.ToolCall, string, bool)

ParseXMLToolCalls 从文本中提取所有 <tool_calls> 块，解析为标准 ToolCall 切片。 返回解析出的工具调用、清理后的文本（移除了 <tool_calls> 块）、以及是否找到。

Types

type BlockingRateLimiter 

type BlockingRateLimiter interface {
	Wait(ctx context.Context) error
}

BlockingRateLimiter 定义阻塞式速率限制接口. 与 llm.RateLimiter（非阻塞式 Allow/AllowN/Reset）不同， BlockingRateLimiter 在超出速率时阻塞等待，适用于中间件链场景.

type Cache 

type Cache interface {
	Key(req *llmpkg.ChatRequest) string
	Get(key string) (*llmpkg.ChatResponse, bool)
	Set(key string, resp *llmpkg.ChatResponse)
}

Cache 定义缓存接口.

type Chain 

type Chain struct {
	// contains filtered or unexported fields
}

Chain 表示中间件链.

func NewChain 

func NewChain(middlewares ...Middleware) *Chain

NewChain 创建新的中间件链.

func (*Chain) Len 

func (c *Chain) Len() int

Len 返回链中的中间件数量.

func (*Chain) Then 

func (c *Chain) Then(h Handler) Handler

Then 用链中的所有中间件包裹一个处理器. 先在锁内拷贝中间件切片，再在锁外执行中间件包裹， 防止中间件回调 Use() 时产生死锁。

func (*Chain) Use 

func (c *Chain) Use(m Middleware) *Chain

Use 将中间件添加到链中.

func (*Chain) UseFront 

func (c *Chain) UseFront(m Middleware) *Chain

UseFront 在链的前部添加中间件.

type EmptyToolsCleaner 

type EmptyToolsCleaner struct{}

EmptyToolsCleaner 空工具列表清理器 当请求的 Tools 为空时，清除 ToolChoice 字段 避免上游 API 返回 400 错误（OpenAI 不允许空 tools 数组时设置 tool_choice）

func NewEmptyToolsCleaner 

func NewEmptyToolsCleaner() *EmptyToolsCleaner

NewEmptyToolsCleaner 创建空工具清理器

func (*EmptyToolsCleaner) Name 

func (r *EmptyToolsCleaner) Name() string

Name 返回改写器名称

func (*EmptyToolsCleaner) Rewrite 

func (r *EmptyToolsCleaner) Rewrite(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)

Rewrite 执行改写

type Handler 

type Handler func(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatResponse, error)

Handler 处理一个请求并返回一个响应.

type MetricsCollector 

type MetricsCollector interface {
	RecordRequest(model string, duration time.Duration, success bool)
	RecordTokens(model string, tokens int)
}

MetricsCollector 定义指标收集接口.

type Middleware 

type Middleware func(next Handler) Handler

Middleware 将处理器包裹并添加额外功能.

func CacheMiddleware 

func CacheMiddleware(cache Cache) Middleware

CacheMiddleware 缓存响应.

func HeadersMiddleware 

func HeadersMiddleware(headers map[string]string) Middleware

HeadersMiddleware 添加自定义头到请求元数据.

func LoggingMiddleware 

func LoggingMiddleware(logFn func(format string, args ...any)) Middleware

LoggingMiddleware 记录请求/响应详情。

func MetricsMiddleware 

func MetricsMiddleware(collector MetricsCollector) Middleware

MetricsMiddleware 收集请求的指标.

func RateLimitMiddleware 

func RateLimitMiddleware(limiter BlockingRateLimiter) Middleware

RateLimitMiddleware 应用速率限制.

func RecoveryMiddleware 

func RecoveryMiddleware(onPanic func(any)) Middleware

RecoveryMiddleware 从 panic 中恢复.

func RetryMiddleware 

func RetryMiddleware(maxRetries int, backoff time.Duration) Middleware

RetryMiddleware 重试失败的请求. 只重试可重试的错误（*types.Error 且 Retryable=true），不可重试的错误立即返回。

func TimeoutMiddleware 

func TimeoutMiddleware(timeout time.Duration) Middleware

TimeoutMiddleware 对请求添加超时.

func TracingMiddleware 

func TracingMiddleware(tracer llmpkg.Tracer) Middleware

TracingMiddleware 添加分布式追踪.

func TransformMiddleware 

func TransformMiddleware(reqTransform func(*llmpkg.ChatRequest), respTransform func(*llmpkg.ChatResponse)) Middleware

TransformMiddleware 转换请求/响应.

func ValidatorMiddleware 

func ValidatorMiddleware(validators ...Validator) Middleware

ValidatorMiddleware 在处理前对请求进行验证.

type MiddlewareProvider added in v1.2.0 

type MiddlewareProvider struct {
	// contains filtered or unexported fields
}

MiddlewareProvider 将中间件链包装为 Provider 接口。 Completion 请求走中间件链，其他方法直接委托给内部 Provider。

func NewMiddlewareProvider added in v1.2.0 

func NewMiddlewareProvider(inner llmpkg.Provider, chain *Chain) *MiddlewareProvider

NewMiddlewareProvider 创建一个中间件包装的 Provider。

func (*MiddlewareProvider) Completion added in v1.2.0 

func (p *MiddlewareProvider) Completion(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatResponse, error)

func (*MiddlewareProvider) Endpoints added in v1.2.0 

func (p *MiddlewareProvider) Endpoints() llmpkg.ProviderEndpoints

func (*MiddlewareProvider) HealthCheck added in v1.2.0 

func (p *MiddlewareProvider) HealthCheck(ctx context.Context) (*llmpkg.HealthStatus, error)

func (*MiddlewareProvider) ListModels added in v1.2.0 

func (p *MiddlewareProvider) ListModels(ctx context.Context) ([]llmpkg.Model, error)

func (*MiddlewareProvider) Name added in v1.2.0 

func (p *MiddlewareProvider) Name() string

func (*MiddlewareProvider) Stream added in v1.2.0 

func (p *MiddlewareProvider) Stream(ctx context.Context, req *llmpkg.ChatRequest) (<-chan llmpkg.StreamChunk, error)

func (*MiddlewareProvider) SupportsNativeFunctionCalling added in v1.2.0 

func (p *MiddlewareProvider) SupportsNativeFunctionCalling() bool

type OtelMetricsAdapter added in v1.2.0 

type OtelMetricsAdapter struct {
	Metrics *observability.Metrics
}

OtelMetricsAdapter 适配 observability.Metrics → middleware.MetricsCollector 接口。

func (*OtelMetricsAdapter) RecordRequest added in v1.2.0 

func (a *OtelMetricsAdapter) RecordRequest(model string, duration time.Duration, success bool)

func (*OtelMetricsAdapter) RecordTokens added in v1.2.0 

func (a *OtelMetricsAdapter) RecordTokens(model string, tokens int)

type PanicError 

type PanicError struct {
	Value any
}

RecoveredPanic 表示已恢复的 panic.

func (*PanicError) Error 

func (e *PanicError) Error() string

func (*PanicError) Unwrap added in v1.5.0 

func (e *PanicError) Unwrap() error

Unwrap exposes the original panic error (when panic payload is error) so callers can use errors.Is/errors.As on recovered panics.

type PromptCacheAdapter added in v1.2.0 

type PromptCacheAdapter struct {
	Cache *cache.MultiLevelCache
}

PromptCacheAdapter 适配 cache.MultiLevelCache → middleware.Cache 接口。

func (*PromptCacheAdapter) Get added in v1.2.0 

func (a *PromptCacheAdapter) Get(key string) (*llmpkg.ChatResponse, bool)

func (*PromptCacheAdapter) Key added in v1.2.0 

func (a *PromptCacheAdapter) Key(req *llmpkg.ChatRequest) string

func (*PromptCacheAdapter) Set added in v1.2.0 

func (a *PromptCacheAdapter) Set(key string, resp *llmpkg.ChatResponse)

type RequestRewriter 

type RequestRewriter interface {
	// Rewrite 改写请求
	// 返回改写后的请求和错误（如果改写失败）
	Rewrite(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)

	// Name 返回改写器名称（用于日志和调试）
	Name() string
}

RequestRewriter 请求改写器接口 用于在请求发送到上游 API 之前进行参数清理和转换

type RewriterChain 

type RewriterChain struct {
	// contains filtered or unexported fields
}

RewriterChain 改写器链 按顺序执行多个改写器，线程安全

func NewRewriterChain 

func NewRewriterChain(rewriters ...RequestRewriter) *RewriterChain

NewRewriterChain 创建改写器链

func (*RewriterChain) AddRewriter 

func (c *RewriterChain) AddRewriter(rewriter RequestRewriter)

AddRewriter 动态添加改写器

func (*RewriterChain) Execute 

func (c *RewriterChain) Execute(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)

Execute 执行改写器链 按顺序执行所有改写器，任何一个失败则中断并返回错误

func (*RewriterChain) GetRewriters 

func (c *RewriterChain) GetRewriters() []RequestRewriter

GetRewriters 获取所有改写器（用于调试）

type Validator 

type Validator interface {
	Validate(req *llmpkg.ChatRequest) error
}

Validator 定义请求验证接口.

type XMLToolCallProvider added in v1.7.1 

type XMLToolCallProvider struct {
	// contains filtered or unexported fields
}

XMLToolCallProvider 包装内部 Provider，在 XML 工具调用模式下：

  • 请求前：将工具定义注入 system prompt，清除 req.Tools（避免 Provider 报错）
  • 响应后：从文本中解析 <tool_calls> 块，转换为标准 ToolCalls

对 ReAct 循环完全透明——它只看到标准的 ToolCalls。

func NewXMLToolCallProvider added in v1.7.1 

func NewXMLToolCallProvider(inner llmpkg.Provider, logger *zap.Logger) *XMLToolCallProvider

NewXMLToolCallProvider 创建 XML 工具调用 Provider 包装器。 logger 可为 nil，此时使用 zap.NewNop()。

func (*XMLToolCallProvider) Completion added in v1.7.1 

func (p *XMLToolCallProvider) Completion(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatResponse, error)

Completion 执行同步补全，在 XML 模式下先注入 prompt 再解析响应

func (*XMLToolCallProvider) Endpoints added in v1.7.1 

func (p *XMLToolCallProvider) Endpoints() llmpkg.ProviderEndpoints

func (*XMLToolCallProvider) HealthCheck added in v1.7.1 

func (p *XMLToolCallProvider) HealthCheck(ctx context.Context) (*llmpkg.HealthStatus, error)

func (*XMLToolCallProvider) ListModels added in v1.7.1 

func (p *XMLToolCallProvider) ListModels(ctx context.Context) ([]llmpkg.Model, error)

func (*XMLToolCallProvider) Name added in v1.7.1 

func (p *XMLToolCallProvider) Name() string

func (*XMLToolCallProvider) Stream added in v1.7.1 

func (p *XMLToolCallProvider) Stream(ctx context.Context, req *llmpkg.ChatRequest) (<-chan llmpkg.StreamChunk, error)

Stream 执行流式补全，在 XML 模式下先注入 prompt 再用流式解析器处理

func (*XMLToolCallProvider) SupportsNativeFunctionCalling added in v1.7.1 

func (p *XMLToolCallProvider) SupportsNativeFunctionCalling() bool

type XMLToolCallStreamParser added in v1.7.1 

type XMLToolCallStreamParser struct {
	// contains filtered or unexported fields
}

XMLToolCallStreamParser 有状态的流式 XML 工具调用解析器。 支持跨 chunk 的部分标签缓冲，当检测到完整 <tool_calls>...</tool_calls> 块时 解析并返回工具调用。

func NewXMLToolCallStreamParser added in v1.7.1 

func NewXMLToolCallStreamParser() *XMLToolCallStreamParser

NewXMLToolCallStreamParser 创建流式解析器

func (*XMLToolCallStreamParser) Feed added in v1.7.1 

func (p *XMLToolCallStreamParser) Feed(text string) (passthrough string, toolCalls []types.ToolCall)

Feed 接收一个 chunk 的文本内容，返回：

  • passthrough: 应直接传递给下游的普通文本
  • toolCalls: 本次 chunk 中解析出的完整工具调用
  • 注意: passthrough 可能为空（内容全部被缓冲或属于 tool_calls 块内部）

func (*XMLToolCallStreamParser) Flush added in v1.7.1 

func (p *XMLToolCallStreamParser) Flush() string

Flush 刷新缓冲区中剩余的内容。在流结束时调用。 返回未被识别为工具调用的残留文本。

type XMLToolRewriter added in v1.7.1 

type XMLToolRewriter struct{}

XMLToolRewriter 在 XML 工具调用模式下，将工具定义注入 system prompt 并清除 req.Tools。 当 req.ToolCallMode != XML 或无工具时为 no-op。

func NewXMLToolRewriter added in v1.7.1 

func NewXMLToolRewriter() *XMLToolRewriter

NewXMLToolRewriter 创建 XML 工具改写器

func (*XMLToolRewriter) Name added in v1.7.1 

func (r *XMLToolRewriter) Name() string

Name 返回改写器名称

func (*XMLToolRewriter) Rewrite added in v1.7.1 

func (r *XMLToolRewriter) Rewrite(ctx context.Context, req *llmpkg.ChatRequest) (*llmpkg.ChatRequest, error)

Rewrite 执行改写：将工具定义注入 system prompt，清除 Tools 和 ToolChoice。 Fix 6: 浅拷贝 ChatRequest + 深拷贝 Messages slice，不修改原始输入。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.