core

Documentation

Index

• Constants
• func GatewayUnavailableError(msg string) *types.Error
• func InvalidCapabilityError(cap Capability) *types.Error
• func InvalidPayloadError(cap Capability, expected string) *types.Error
• type Capability
• type CapabilityHints
  • func (h *CapabilityHints) Normalize()
• type ChatRerankBinding
• type Cost
• type Gateway
• type ProviderDecision
• type RerankProviderResolver
• type RoutePolicy
• type UnifiedChunk
• type UnifiedRequest
• type UnifiedResponse
• type Usage
  • func (u Usage) IsZero() bool

Constants

const (
	// MetadataKeyChatProvider is the canonical metadata key for chat provider hint.
	MetadataKeyChatProvider = "chat_provider"
)

Functions

func GatewayUnavailableError

func GatewayUnavailableError(msg string) *types.Error

GatewayUnavailableError 表示 gateway 缺少执行依赖。

func InvalidCapabilityError

func InvalidCapabilityError(cap Capability) *types.Error

InvalidCapabilityError 表示不支持的能力类型。

func InvalidPayloadError

func InvalidPayloadError(cap Capability, expected string) *types.Error

InvalidPayloadError 表示 payload 类型或内容错误。

Types

type Capability

type Capability string

Capability 标识统一入口支持的能力类型。

const (
	CapabilityChat       Capability = "chat"
	CapabilityTools      Capability = "tools"
	CapabilityImage      Capability = "image"
	CapabilityVideo      Capability = "video"
	CapabilityAudio      Capability = "audio"
	CapabilityEmbedding  Capability = "embedding"
	CapabilityRerank     Capability = "rerank"
	CapabilityModeration Capability = "moderation"
	CapabilityMusic      Capability = "music"
	CapabilityThreeD     Capability = "threed"
	CapabilityAvatar     Capability = "avatar"
)

type CapabilityHints

type CapabilityHints struct {
	ChatProvider   string `json:"chat_provider,omitempty"`
	RerankProvider string `json:"rerank_provider,omitempty"`
}

CapabilityHints carries normalized cross-capability routing hints.

func (*CapabilityHints) Normalize

func (h *CapabilityHints) Normalize()

Normalize trims whitespace in all hint fields.

type ChatRerankBinding

type ChatRerankBinding struct {
	ChatProvider   string `json:"chat_provider"`
	RerankProvider string `json:"rerank_provider"`
}

ChatRerankBinding 定义 chat provider 到 rerank provider 的显式绑定关系。

type Cost

type Cost struct {
	AmountUSD float64 `json:"amount_usd,omitempty"`
	Currency  string  `json:"currency,omitempty"`
}

Cost 统一记录成本信息。

type Gateway

type Gateway interface {
	Invoke(ctx context.Context, req *UnifiedRequest) (*UnifiedResponse, error)
	Stream(ctx context.Context, req *UnifiedRequest) (<-chan UnifiedChunk, error)
}

Gateway 定义 LLM 统一入口。

type ProviderDecision

type ProviderDecision struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	BaseURL  string `json:"base_url,omitempty"`
	Strategy string `json:"strategy,omitempty"`
}

ProviderDecision 记录路由最终决策。

type RerankProviderResolver

type RerankProviderResolver interface {
	ResolveRerankProvider(chatProvider string) string
}

RerankProviderResolver 定义 rerank provider 解析契约，避免上层依赖 provider 私有实现细节。

type RoutePolicy

type RoutePolicy string

RoutePolicy 定义统一路由策略标签。

const (
	RoutePolicyCostFirst    RoutePolicy = "cost_first"
	RoutePolicyHealthFirst  RoutePolicy = "health_first"
	RoutePolicyLatencyFirst RoutePolicy = "latency_first"
	RoutePolicyBalanced     RoutePolicy = "balanced"
)

type UnifiedChunk

type UnifiedChunk struct {
	Output           any              `json:"output,omitempty"`
	Usage            *Usage           `json:"usage,omitempty"`
	Cost             *Cost            `json:"cost,omitempty"`
	TraceID          string           `json:"trace_id,omitempty"`
	ProviderDecision ProviderDecision `json:"provider_decision,omitempty"`
	Done             bool             `json:"done,omitempty"`
	Err              *types.Error     `json:"error,omitempty"`
}

UnifiedChunk 是统一入口流式响应块。

type UnifiedRequest

type UnifiedRequest struct {
	Capability   Capability        `json:"capability"`
	ProviderHint string            `json:"provider_hint,omitempty"`
	ModelHint    string            `json:"model_hint,omitempty"`
	RoutePolicy  RoutePolicy       `json:"route_policy,omitempty"`
	TraceID      string            `json:"trace_id,omitempty"`
	Hints        CapabilityHints   `json:"hints,omitempty"`
	Payload      any               `json:"payload,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	Tags         []string          `json:"tags,omitempty"`
}

UnifiedRequest 是统一入口请求结构。

type UnifiedResponse

type UnifiedResponse struct {
	Output           any              `json:"output,omitempty"`
	Usage            Usage            `json:"usage"`
	Cost             Cost             `json:"cost"`
	TraceID          string           `json:"trace_id,omitempty"`
	ProviderDecision ProviderDecision `json:"provider_decision,omitempty"`
}

UnifiedResponse 是统一入口同步响应结构。

type Usage

type Usage struct {
	PromptTokens     int `json:"prompt_tokens,omitempty"`
	CompletionTokens int `json:"completion_tokens,omitempty"`
	TotalTokens      int `json:"total_tokens,omitempty"`

	InputUnits  int `json:"input_units,omitempty"`
	OutputUnits int `json:"output_units,omitempty"`
	TotalUnits  int `json:"total_units,omitempty"`
}

Usage 统一记录 token 与能力单位消耗。

func (Usage) IsZero

func (u Usage) IsZero() bool

IsZero 判断 usage 是否为空统计。