docs(comments): 注释中文化 · internal/runtime/model + internal/services/backthink（54 文件，纯替换）
- 只翻注释/文档字符串：`go/scanner` 剥注释后按 token 序列+literal 逐 token 比对，**54/54 文件 SAME**；
改动文件总行数与 HEAD 漂移 = 0（严格 1:1，无合并/拆行）
- 裁决编号与 design 节号逐字保留（03.4.1/03.4.2/03.4.3/14.4.1/14.4.5/07.4.2-4、design/04 §3.1/§3.2 等）；
`chat_template_kwargs` / `enable_thinking` / `reasoning_effort` / `thinking:{type}` 字段名与形状说明未动
- 存疑译法（已登记）：`persona` 在叙事语境用「角色」、标识符语境保留 `persona`（仓库既有模块本身混用）；
`rung`→「级」；`provider` 存在「提供商/提供者」两种落笔（可按需一键统一）
- 复核：build/vet 绿 + 两包测试绿；gofmt 干净；残留英文注释 0 条
- 既有存量（未修，只报告）：`model/anthropic_test.go` 612 行 >500；`applyAnthropicEvent` 115 行 >80
This commit is contained in:
AskaEth committed
1 parent
f5cf117482
commit
3dc1232bc2
54 files changed
+1923
-1923
No files matched your search
@@ -7,48 +7,48 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
|
||||
)
|
||||
|
||||
// Step binds a model name to an Adapter for one entry in a fallback chain. An
|
||||
// empty Model keeps the incoming Request.Model.
|
||||
// Step 把模型名与 Adapter 绑定成降级链里的一项。
|
||||
// Model 为空时沿用传入 Request.Model。
|
||||
type Step struct {
|
||||
Model string
|
||||
Adapter Adapter
|
||||
}
|
||||
|
||||
// Chain is an Adapter that tries its steps in order and returns the first
|
||||
// successful response. It implements Adapter, so it can be used anywhere a
|
||||
// single provider is expected.
|
||||
// Chain 是一个按顺序尝试各步骤、返回第一个
|
||||
// 成功响应的 Adapter。它实现了 Adapter，因此任何期望单个
|
||||
// 提供商的地方都能使用它。
|
||||
type Chain struct {
|
||||
steps []Step
|
||||
// groupMaxTokens is the active model group's own budget (models.json
|
||||
// maxTokens). When > 0 it applies to every step of the group's chain and
|
||||
// wins over fallbackMaxTokens.
|
||||
// groupMaxTokens 是生效模型组自己的预算（models.json
|
||||
// maxTokens）。大于 0 时作用于该组链的每一步，
|
||||
// 并优先于 fallbackMaxTokens。
|
||||
groupMaxTokens int
|
||||
// fallbackMaxTokens is the last-resort budget (LLM_FALLBACK_MAX_TOKENS). It
|
||||
// only applies to the final step of a chain that actually has a fallback.
|
||||
// fallbackMaxTokens 是最后的兜底预算（LLM_FALLBACK_MAX_TOKENS）。
|
||||
// 它只作用于确实有降级步骤的链的最后一个步骤。
|
||||
fallbackMaxTokens int
|
||||
}
|
||||
|
||||
// NewChain builds a fallback chain from the given steps.
|
||||
// NewChain 由给定步骤构建降级链。
|
||||
func NewChain(steps ...Step) *Chain {
|
||||
return &Chain{steps: steps}
|
||||
}
|
||||
|
||||
// WithTokenBudget sets the chain's token budgets: the active group's own budget
|
||||
// and the last-resort fallback budget. It must be called before the chain is
|
||||
// published to concurrent callers (the runtime builds a fresh chain per
|
||||
// snapshot and swaps it in atomically), so the fields are never mutated in
|
||||
// flight.
|
||||
// WithTokenBudget 设置链的 token 预算：生效组自己的预算
|
||||
// 与最后的兜底预算。必须在链被发布给并发调用方之前调用
|
||||
// （运行时为每个快照构建一条新链并原子换入），
|
||||
// 快照并原子换入），所以这些字段绝不会在运行中
|
||||
// 被改写。
|
||||
func (c *Chain) WithTokenBudget(groupMaxTokens, fallbackMaxTokens int) *Chain {
|
||||
c.groupMaxTokens = groupMaxTokens
|
||||
c.fallbackMaxTokens = fallbackMaxTokens
|
||||
return c
|
||||
}
|
||||
|
||||
// stepModel picks the model name for step idx of the chain. The primary step
|
||||
// prefers the request's routed model — the per-persona / per-request decision the
|
||||
// Router produced — over the group's configured model, so a routing decision is
|
||||
// never silently discarded. Every fallback step pins its own configured model, so
|
||||
// a degradation never re-sends the primary model name to a different endpoint
|
||||
// stepModel 选出链上第 idx 步的模型名。主步骤
|
||||
// 优先用请求中被路由的模型——即 Router 产出的按角色/按请求
|
||||
// 决策——而不是组里配置的模型，这样一个路由决策
|
||||
// 绝不会被静默丢弃。每个降级步骤都钉住自己配置的模型，
|
||||
// 因此一次降级绝不会把主模型名重发给另一个端点。
|
||||
// (裁决 03.4.1: per-persona 路由必须真的落到请求上).
|
||||
func stepModel(req Request, idx int, configured string) string {
|
||||
if idx == 0 && req.Model != "" {
|
||||
@@ -57,12 +57,12 @@ func stepModel(req Request, idx int, configured string) string {
|
||||
return configured
|
||||
}
|
||||
|
||||
// applyBudget resolves the effective MaxTokens for step idx, honoring the
|
||||
// precedence: an explicit Request.MaxTokens > the group's MaxTokens > the
|
||||
// last-resort LLM_FALLBACK_MAX_TOKENS > the adapter default. The last-resort
|
||||
// budget only applies when the chain really has a fallback step (len > 1) and
|
||||
// only to that final step; a single-step chain is a primary model, not a
|
||||
// fallback, so its adapter default is left untouched.
|
||||
// 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
|
||||
@@ -77,20 +77,20 @@ func (c *Chain) applyBudget(req Request, idx int) Request {
|
||||
return req
|
||||
}
|
||||
|
||||
// NewOpenAIChatChain builds a fallback chain from a single supplier config: the
|
||||
// primary model first, then cfg.Fallback (when set and distinct), both served
|
||||
// by an OpenAIChatAdapter against the same OpenAI-compatible endpoint. It
|
||||
// delegates to the provider-aware builder so the OpenAI path and the factory stay
|
||||
// in sync. It returns ErrNoModel when no base URL or primary model is configured.
|
||||
// NewOpenAIChatChain 由单份供应商配置构建降级链：先
|
||||
// 主模型，再 cfg.Fallback（已设置且不同时），两者都由
|
||||
// 同一个 OpenAI 兼容端点上的 OpenAIChatAdapter 服务。它
|
||||
// 委托给提供商感知的构建器，使 OpenAI 路径与工厂保持
|
||||
// 一致。未配置 base URL 或主模型时返回 ErrNoModel。
|
||||
func NewOpenAIChatChain(cfg config.LLMConfig, opts ...OpenAIOption) (*Chain, error) {
|
||||
return newOpenAIChain(cfg, opts...)
|
||||
}
|
||||
|
||||
// Name returns the chain identifier.
|
||||
// Name 返回链标识。
|
||||
func (c *Chain) Name() string { return "fallback" }
|
||||
|
||||
// Chat tries each step in order and returns the first success. If every step
|
||||
// fails, the last error is returned wrapped as ErrUpstream.
|
||||
// Chat 按顺序尝试每一步并返回第一个成功的结果。若每一步
|
||||
// 都失败，则把最后一个错误包成 ErrUpstream 返回。
|
||||
func (c *Chain) Chat(ctx context.Context, req Request, opts Options) (Response, error) {
|
||||
if len(c.steps) == 0 {
|
||||
return Response{}, ErrNoSteps
|
||||
@@ -110,10 +110,10 @@ func (c *Chain) Chat(ctx context.Context, req Request, opts Options) (Response,
|
||||
return Response{}, fmt.Errorf("model: %w: %v", ErrUpstream, lastErr)
|
||||
}
|
||||
|
||||
// ChatStream tries each step in order. If a step fails before delivering any
|
||||
// event, the chain moves to the next step; once a step has delivered output it
|
||||
// is committed, so a mid-stream failure surfaces as an error rather than mixing
|
||||
// content across providers.
|
||||
// ChatStream 按顺序尝试每一步。若某步在交付任何事件之前
|
||||
// 就失败，链会移到下一步；一旦某步已交付输出，
|
||||
// 它就被视为已提交，因此流中途的失败会作为错误浮出，而不会把
|
||||
// 不同提供商的内容混在一起。
|
||||
func (c *Chain) ChatStream(ctx context.Context, req Request, onEvent func(StreamEvent)) (Response, error) {
|
||||
if len(c.steps) == 0 {
|
||||
return Response{}, ErrNoSteps
|
||||
|
||||
Reference in new issue
Block a user