config

Documentation

Overview

Package config 定义 core 的配置文件模型、加载与校验。

配置只描述事实，不承载行为：它不知道渠道客户端与插件宿主的存在，装配由 server 层完成。凭据一律只写环境变量名，配置文件里不出现密钥。

Index

• Constants
• func Match(pattern, name string) bool
• type Affinity
• type Auth
• type Channel
• type Config
  • func Load(path string) (*Config, error)
  • func Parse(reader io.Reader) (*Config, error)
  • func (c *Config) AffinityMinPrefixBytes() int
  • func (c *Config) AffinityTTL() time.Duration
  • func (c *Config) AffinityTableSize() int
  • func (c *Config) ChannelByName(name string) (Channel, bool)
  • func (c *Config) Defaults()
  • func (c *Config) EnabledPlugins() []Plugin
  • func (c *Config) PluginConfig(key string) map[string]any
  • func (c *Config) Resolve(model string) []Route
  • func (c *Config) Validate() error
• type Duration
  • func (d Duration) Duration() time.Duration
  • func (d Duration) MarshalYAML() (any, error)
  • func (d Duration) String() string
  • func (d *Duration) UnmarshalJSON(data []byte) error
  • func (d *Duration) UnmarshalYAML(unmarshal func(any) error) error
• type Log
• type Matcher
  • func CompileMatch(pattern string) (Matcher, error)
  • func (m Matcher) Match(name string) bool
  • func (m Matcher) Pattern() string
• type Model
• type Plugin
• type Plugins
• type Route

Constants

const (
	DefaultListen       = "127.0.0.1:8787"
	DefaultLogFormat    = "json"
	DefaultLogLevel     = "info"
	DefaultTimeout      = 120 * time.Second
	DefaultPluginDir    = "plugins"
	DefaultMaxBodyBytes = 32 << 20
	// MaxRetries 是渠道重试次数的上限，与 channel.MaxRetries 保持一致。
	MaxRetries = 10
	// 渠道亲和的参数默认值。
	DefaultAffinityTableSize = 8192
	DefaultAffinityTTL       = 10 * time.Minute
	// DefaultAffinityMinPrefixBytes 是前缀的字节下限。按中英文混排估算，4096 字节
	// 大致是一千出头到两千 tokens，落在上游最小可缓存长度（按模型 512 到 4096
	// tokens）的下半段。它是个启发式，估不准时应当按实际模型调高。
	DefaultAffinityMinPrefixBytes = 4096
)

默认值。只在这里写一次，Load 与文档都以它为准。

Functions

func Match

func Match(pattern, name string) bool

Match 报告名字是否命中该模式。模式不合法时返回 false。

Types

type Affinity

type Affinity struct {
	// TableSize 是前缀链记忆的条数上限。不大于零时没有会话标识的客户端不参与
	// 亲和。
	TableSize *int `yaml:"table_size"`
	// TTL 是前缀链记忆的寿命，按上游缓存的寿命设。
	TTL Duration `yaml:"ttl"`
	// MinPrefixBytes 是前缀的字节下限，短于它时不做亲和。
	MinPrefixBytes *int `yaml:"min_prefix_bytes"`
}

Affinity 是渠道亲和的参数。哪些渠道参与亲和由 Model.Affinity 的组名决定， 这里只放参数。

三个字段都是可选的，不写就用本文件里的默认常量。用指针是为了把「没写」与 「显式写成 0」区分开：最小前缀长度写成 0 表示不做这个判断。

type Auth

type Auth struct {
	// Style 取 bearer、x-api-key、query、custom 或 none。
	Style string `yaml:"style"`
	// KeyEnv 是凭据所在的环境变量名。
	KeyEnv string `yaml:"key_env"`
	// Header 是 Style 为 custom 时的请求头名。
	Header string `yaml:"header"`
	// Query 是 Style 为 query 时的查询参数名。
	Query string `yaml:"query"`
}

Auth 是渠道的鉴权方式。凭据值只从 KeyEnv 指定的环境变量读取。

type Channel

type Channel struct {
	Name       string            `yaml:"name"`
	Dialect    string            `yaml:"dialect"`
	BaseURL    string            `yaml:"base_url"`
	Path       string            `yaml:"path"`
	Auth       Auth              `yaml:"auth"`
	Timeout    Duration          `yaml:"timeout"`
	MaxRetries *int              `yaml:"max_retries"`
	Headers    map[string]string `yaml:"headers"`
}

Channel 是一个上游渠道。BaseURL 是渠道基址，Path 为空时按方言取默认路径。

type Config

type Config struct {
	// Path 是配置文件的绝对路径，由 Load 填入。Parse 不填。
	Path     string    `yaml:"-"`
	Listen   string    `yaml:"listen"`
	Log      Log       `yaml:"log"`
	Channels []Channel `yaml:"channels"`
	Models   []Model   `yaml:"models"`
	Plugins  Plugins   `yaml:"plugins"`
	Affinity Affinity  `yaml:"affinity"`
}

Config 是一份完整的服务配置。

func Load

func Load(path string) (*Config, error)

Load 读取并校验配置文件。

解码开启 KnownFields：拼错的字段在加载时报错，而不是被静默忽略。相对路径一律 以配置文件所在目录为基准，因此工作目录变化不会改变行为。

func Parse

func Parse(reader io.Reader) (*Config, error)

Parse 从阅读器解析配置并校验。相对路径保留原样，调用方需要时自行归一。

func (*Config) AffinityMinPrefixBytes

func (c *Config) AffinityMinPrefixBytes() int

AffinityMinPrefixBytes 返回前缀的字节下限。返回零表示不做这个判断。

func (*Config) AffinityTTL

func (c *Config) AffinityTTL() time.Duration

AffinityTTL 返回前缀链记忆的寿命。

func (*Config) AffinityTableSize

func (c *Config) AffinityTableSize() int

AffinityTableSize 返回前缀链记忆的条数上限。

func (*Config) ChannelByName

func (c *Config) ChannelByName(name string) (Channel, bool)

ChannelByName 按名字取渠道配置。

func (*Config) Defaults

func (c *Config) Defaults()

Defaults 填入未写的默认值。校验前调用。

func (*Config) EnabledPlugins

func (c *Config) EnabledPlugins() []Plugin

EnabledPlugins 返回启用中的插件，按 order 升序排列；order 相同时保持配置顺序。

func (*Config) PluginConfig

func (c *Config) PluginConfig(key string) map[string]any

PluginConfig 返回指定插件的配置对象，未配置时返回空 map。

func (*Config) Resolve

func (c *Config) Resolve(model string) []Route

Resolve 返回该模型名的候选路由，按配置顺序排列。没有匹配项时返回空切片。

func (*Config) Validate

func (c *Config) Validate() error

Validate 校验配置。返回的错误说明第几条配置出了什么问题。

type Duration

type Duration time.Duration

Duration 是配置里可读的时长，写法与 time.ParseDuration 一致，例如 120s、1m30s。 为兼容只写数字的配置，纯数字按秒解释。

func (Duration) Duration

func (d Duration) Duration() time.Duration

Duration 返回标准库时长。

func (Duration) MarshalYAML

func (d Duration) MarshalYAML() (any, error)

MarshalYAML 按 time.Duration 的字符串形式写出。

func (Duration) String

func (d Duration) String() string

String 返回可读时长。

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON 让 Duration 在 JSON 里也能工作，便于 CLI 输出配置快照。

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML 支持字符串与数字两种写法。

type Log

type Log struct {
	Format string `yaml:"format"`
	Level  string `yaml:"level"`
}

Log 是日志配置。

type Matcher

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

Matcher 是一个已校验的模型名匹配器。

func CompileMatch

func CompileMatch(pattern string) (Matcher, error)

CompileMatch 校验匹配式并返回匹配器。

支持两个通配符：* 匹配任意长度的一段（含 / 与 :），? 匹配一个字符。 其余字符按字面比较。模型名按 UTF-8 字符逐个比较。

func (Matcher) Match

func (m Matcher) Match(name string) bool

Match 报告名字是否命中。按 rune 比较，通配符不跨字符。

func (Matcher) Pattern

func (m Matcher) Pattern() string

Pattern 返回原始匹配式。

type Model

type Model struct {
	Match    string `yaml:"match"`
	Channel  string `yaml:"channel"`
	Upstream string `yaml:"upstream"`
	Dialect  string `yaml:"dialect"`
	Affinity string `yaml:"affinity"`
}

Model 是一条模型路由规则。Match 支持 * 通配，同一个模型可以有多条规则， 按配置顺序依次尝试。

Upstream 是发往上游的模型名，可以写 ${model} 占位符，替换成客户端请求里 经插件改写后真正参与匹配的那个模型名。写法与校验规则见 Validate 与 docs/config.md。

Affinity 是渠道亲和的组名。命中该模型的规则里，组名相同的候选组成一个池， 池里的渠道被当作可互换的；同一段会话的连续请求会在池内粘住一条，池外的候选 按配置顺序排在池后面兜底。留空表示不参与。

type Plugin

type Plugin struct {
	Key     string         `yaml:"key"`
	Enabled bool           `yaml:"enabled"`
	Order   int            `yaml:"order"`
	Config  map[string]any `yaml:"config"`
}

Plugin 是一个插件的启用状态与顺序。

type Plugins

type Plugins struct {
	// Dir 是插件目录，相对路径以配置文件所在目录为基准。
	Dir  string   `yaml:"dir"`
	List []Plugin `yaml:"list"`
}

Plugins 是插件目录与插件清单。

type Route

type Route struct {
	Channel  string
	Upstream string
	Dialect  dialect.Name
	// Affinity 取自语规则，是这条候选所属的亲和组名，空串表示不参与。
	Affinity string
}

Route 是解析后的一条候选路由。