Cyrene_v2/internal/runtime/model/fallback.go

package model

import (
	"context"
	"fmt"

	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)

// Step 把模型名与 Adapter 绑定成降级链里的一项。
// Model 为空时沿用传入 Request.Model。
type Step struct {
	Model   string
	Adapter Adapter
}

// Chain 是一个按顺序尝试各步骤、返回第一个
// 成功响应的 Adapter。它实现了 Adapter，因此任何期望单个
// 提供商的地方都能使用它。
type Chain struct {
	steps []Step
	// groupMaxTokens 是生效模型组自己的预算（models.json
	// maxTokens）。大于 0 时作用于该组链的每一步，
	// 并优先于 fallbackMaxTokens。
	groupMaxTokens int
	// fallbackMaxTokens 是最后的兜底预算（LLM_FALLBACK_MAX_TOKENS）。
	// 它只作用于确实有降级步骤的链的最后一个步骤。
	fallbackMaxTokens int
}

// NewChain 由给定步骤构建降级链。
func NewChain(steps ...Step) *Chain {
	return &Chain{steps: steps}
}

// WithTokenBudget 设置链的 token 预算：生效组自己的预算
// 与最后的兜底预算。必须在链被发布给并发调用方之前调用
// （运行时为每个快照构建一条新链并原子换入），
// 快照并原子换入），所以这些字段绝不会在运行中
// 被改写。
func (c *Chain) WithTokenBudget(groupMaxTokens, fallbackMaxTokens int) *Chain {
	c.groupMaxTokens = groupMaxTokens
	c.fallbackMaxTokens = fallbackMaxTokens
	return c
}

// stepModel 选出链上第 idx 步的模型名。主步骤
// 优先用请求中被路由的模型——即 Router 产出的按角色/按请求
// 决策——而不是组里配置的模型，这样一个路由决策
// 绝不会被静默丢弃。每个降级步骤都钉住自己配置的模型，
// 因此一次降级绝不会把主模型名重发给另一个端点。
// (裁决 03.4.1: per-persona 路由必须真的落到请求上).
func stepModel(req Request, idx int, configured string) string {
	if idx == 0 && req.Model != "" {
		return req.Model
	}
	return configured
}

// applyBudget 解出第 idx 步实际生效的 MaxTokens，遵循
// 优先级：显式的 Request.MaxTokens > 组自己的 MaxTokens >
// 兜底的 LLM_FALLBACK_MAX_TOKENS > 适配器默认值。兜底
// 预算只在链确实有降级步骤（len > 1）时生效，
// 且只作用于最后那一步；单步链就是主模型、并非
// 降级，所以它的适配器默认值保持不动。
func (c *Chain) applyBudget(req Request, idx int) Request {
	if req.MaxTokens != 0 {
		return req
	}
	if c.groupMaxTokens > 0 {
		req.MaxTokens = c.groupMaxTokens
		return req
	}
	if c.fallbackMaxTokens > 0 && len(c.steps) > 1 && idx == len(c.steps)-1 {
		req.MaxTokens = c.fallbackMaxTokens
	}
	return req
}

// NewOpenAIChatChain 由单份供应商配置构建降级链：先
// 主模型，再 cfg.Fallback（已设置且不同时），两者都由
// 同一个 OpenAI 兼容端点上的 OpenAIChatAdapter 服务。它
// 委托给提供商感知的构建器，使 OpenAI 路径与工厂保持
// 一致。未配置 base URL 或主模型时返回 ErrNoModel。
func NewOpenAIChatChain(cfg config.LLMConfig, opts ...OpenAIOption) (*Chain, error) {
	return newOpenAIChain(cfg, opts...)
}

// Name 返回链标识。
func (c *Chain) Name() string { return "fallback" }

// Chat 按顺序尝试每一步并返回第一个成功的结果。若每一步
// 都失败，则把最后一个错误包成 ErrUpstream 返回。
func (c *Chain) Chat(ctx context.Context, req Request, opts Options) (Response, error) {
	if len(c.steps) == 0 {
		return Response{}, ErrNoSteps
	}
	var lastErr error
	for i, s := range c.steps {
		stepReq := c.applyBudget(req, i)
		if m := stepModel(req, i, s.Model); m != "" {
			stepReq.Model = m
		}
		resp, err := s.Adapter.Chat(ctx, stepReq, opts)
		if err == nil {
			return resp, nil
		}
		lastErr = err
	}
	return Response{}, fmt.Errorf("model: %w: %v", ErrUpstream, lastErr)
}

// ChatStream 按顺序尝试每一步。若某步在交付任何事件之前
// 就失败，链会移到下一步；一旦某步已交付输出，
// 它就被视为已提交，因此流中途的失败会作为错误浮出，而不会把
// 不同提供商的内容混在一起。
func (c *Chain) ChatStream(ctx context.Context, req Request, onEvent func(StreamEvent)) (Response, error) {
	if len(c.steps) == 0 {
		return Response{}, ErrNoSteps
	}
	var lastErr error
	for i, s := range c.steps {
		stepReq := c.applyBudget(req, i)
		if m := stepModel(req, i, s.Model); m != "" {
			stepReq.Model = m
		}
		delivered := false
		wrapped := func(ev StreamEvent) {
			delivered = true
			if onEvent != nil {
				onEvent(ev)
			}
		}
		resp, err := s.Adapter.ChatStream(ctx, stepReq, wrapped)
		if err == nil {
			return resp, nil
		}
		if delivered {
			return Response{}, fmt.Errorf("model: %w: stream step %q failed after partial output: %v", ErrUpstream, s.Model, err)
		}
		lastErr = err
	}
	return Response{}, fmt.Errorf("model: %w: %v", ErrUpstream, lastErr)
}