providers

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Feb 23, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

概述

包 providers 提供跨模型服务商的通用适配与辅助能力,是所有具体 Provider 实现的公共基础层。各服务商子包(openai、anthropic、deepseek 等)依赖本包 完成请求/响应转换、错误映射、多模态调用等共享逻辑。

核心类型

  • BaseProviderConfig — 所有 Provider 共享的基础配置(APIKey、BaseURL、Model、Timeout)
  • OpenAICompat* 系列 — OpenAI 兼容 API 的通用请求/响应/工具调用结构体
  • RetryableProvider — 带指数退避重试的 Provider 包装器
  • RetryConfig — 重试策略配置(最大次数、初始延迟、退避因子)

核心函数

  • MapHTTPError — 将 HTTP 状态码映射为语义化的 llm.Error(含 Retryable 标记)
  • ConvertMessagesToOpenAI / ConvertToolsToOpenAI — 统一消息与工具格式转换
  • ToLLMChatResponse — OpenAI 兼容响应到 llm.ChatResponse 的转换
  • ChooseModel — 按优先级选择模型(请求 > 默认 > 兜底)
  • ListModelsOpenAICompat — 通用模型列表获取

多模态辅助

  • GenerateImageOpenAICompat — 通用图像生成
  • GenerateVideoOpenAICompat — 通用视频生成
  • GenerateAudioOpenAICompat — 通用音频生成
  • CreateEmbeddingOpenAICompat — 通用 Embedding 生成
  • NotSupportedError — 不支持能力的标准错误构造

支持能力

  • 统一错误语义映射(401/403/429/5xx/529 等)
  • 指数退避重试(Completion 与 Stream 连接阶段)
  • OpenAI 兼容格式的请求/响应序列化
  • 多模态生成(图像、视频、音频、Embedding)的通用 HTTP 执行
  • Bearer Token 标准认证 header 构建

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BearerTokenHeaders

func BearerTokenHeaders(r *http.Request, apiKey string)

BearerTokenHeaders 是标准的 Bearer token 认证 header 构建函数。 用于 multimodal helper 函数的 buildHeadersFunc 参数,避免各 provider 重复定义匿名函数。

func ChooseModel

func ChooseModel(req *llm.ChatRequest, defaultModel, fallbackModel string) string

ChooseModel 根据请求和默认值选择模型

func ConvertResponseFormat added in v1.0.0

func ConvertResponseFormat(rf *llm.ResponseFormat) any

ConvertResponseFormat 将 llm.ResponseFormat 转换为 OpenAI 兼容的 response_format 参数。 返回 nil 表示不设置 response_format。

func CreateEmbeddingOpenAICompat

func CreateEmbeddingOpenAICompat(ctx context.Context, client *http.Client, baseURL, apiKey, providerName, endpoint string, req *llm.EmbeddingRequest, buildHeadersFunc func(*http.Request, string)) (*llm.EmbeddingResponse, error)

CreateEmbeddingOpenAICompat 通用的 OpenAI 兼容 Embedding 函数

func GenerateAudioOpenAICompat

func GenerateAudioOpenAICompat(ctx context.Context, client *http.Client, baseURL, apiKey, providerName, endpoint string, req *llm.AudioGenerationRequest, buildHeadersFunc func(*http.Request, string)) (*llm.AudioGenerationResponse, error)

GenerateAudioOpenAICompat 通用的 OpenAI 兼容音频生成函数

func GenerateImageOpenAICompat

func GenerateImageOpenAICompat(ctx context.Context, client *http.Client, baseURL, apiKey, providerName, endpoint string, req *llm.ImageGenerationRequest, buildHeadersFunc func(*http.Request, string)) (*llm.ImageGenerationResponse, error)

GenerateImageOpenAICompat 通用的 OpenAI 兼容图像生成函数

func GenerateVideoOpenAICompat

func GenerateVideoOpenAICompat(ctx context.Context, client *http.Client, baseURL, apiKey, providerName, endpoint string, req *llm.VideoGenerationRequest, buildHeadersFunc func(*http.Request, string)) (*llm.VideoGenerationResponse, error)

GenerateVideoOpenAICompat 通用的 OpenAI 兼容视频生成函数

func ListModelsOpenAICompat

func ListModelsOpenAICompat(ctx context.Context, client *http.Client, baseURL, apiKey, providerName, modelsEndpoint string, buildHeadersFunc func(*http.Request, string)) ([]llm.Model, error)

ListModelsOpenAICompat 通用的 OpenAI 兼容 Provider 模型列表获取函数

func MapHTTPError

func MapHTTPError(status int, msg string, provider string) *llm.Error

MapHTTPError 将 HTTP 状态码映射为带有合适重试标记的 llm.Error 这是所有提供者使用的通用错误映射函数

func NotSupportedError

func NotSupportedError(providerName, feature string) *llm.Error

NotSupportedError 返回不支持的错误

func ReadErrorMessage

func ReadErrorMessage(body io.Reader) string

ReadErrorMessage 读取响应体中的错误消息 尝试解析 JSON 错误响应,失败则回退到原始文本

func SafeCloseBody

func SafeCloseBody(body io.ReadCloser)

SafeCloseBody 安全关闭 HTTP 响应体并忽略错误

func ToLLMChatResponse

func ToLLMChatResponse(oa OpenAICompatResponse, provider string) *llm.ChatResponse

ToLLMChatResponse 将 OpenAI 兼容的响应转换为 llm.ChatResponse.

Types

type APIKeyEntry added in v1.0.0

type APIKeyEntry struct {
	Key     string `json:"key" yaml:"key"`
	BaseURL string `json:"base_url,omitempty" yaml:"base_url,omitempty"`
	Weight  int    `json:"weight,omitempty" yaml:"weight,omitempty"`
}

APIKeyEntry 结构化 API Key 条目,每个 Key 可绑定独立的 BaseURL 和权重

type BaseProviderConfig

type BaseProviderConfig struct {
	APIKey  string        `json:"api_key" yaml:"api_key"`
	APIKeys []APIKeyEntry `json:"api_keys,omitempty" yaml:"api_keys,omitempty"` // 多 API Key 支持,轮询使用
	BaseURL string        `json:"base_url" yaml:"base_url"`
	Model   string        `json:"model,omitempty" yaml:"model,omitempty"`
	Models  []string      `json:"models,omitempty" yaml:"models,omitempty"` // 可用模型白名单
	Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

BaseProviderConfig 所有 Provider 共享的基础配置字段。 通过嵌入此结构体,各 Provider 的 Config 自动获得 APIKey、BaseURL、Model、Timeout 四个字段, 避免重复定义。

type ClaudeConfig

type ClaudeConfig struct {
	BaseProviderConfig `yaml:",inline"`
	AuthType           string `json:"auth_type,omitempty" yaml:"auth_type,omitempty"`                 // "api_key"(默认) | "bearer"
	AnthropicVersion   string `json:"anthropic_version,omitempty" yaml:"anthropic_version,omitempty"` // 默认 "2023-06-01"
}

ClaudeConfig Claude Provider 配置

type DeepSeekConfig

type DeepSeekConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

DeepSeekConfig DeepSeek Provider 配置

type DoubaoConfig

type DoubaoConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

DoubaoConfig ByteDance Doubao Provider 配置

type GLMConfig

type GLMConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

GLMConfig Zhipu AI GLM Provider 配置

type GeminiConfig

type GeminiConfig struct {
	BaseProviderConfig `yaml:",inline"`
	ProjectID          string `json:"project_id,omitempty" yaml:"project_id,omitempty"`
	Region             string `json:"region,omitempty" yaml:"region,omitempty"`
	AuthType           string `json:"auth_type,omitempty" yaml:"auth_type,omitempty"` // "api_key"(默认) | "oauth"
}

GeminiConfig Gemini Provider 配置

type GrokConfig

type GrokConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

GrokConfig xAI Grok Provider 配置

type HunyuanConfig

type HunyuanConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

HunyuanConfig Tencent Hunyuan Provider 配置

type KimiConfig

type KimiConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

KimiConfig Moonshot Kimi Provider 配置

type LlamaConfig

type LlamaConfig struct {
	BaseProviderConfig `yaml:",inline"`
	Provider           string `json:"provider,omitempty" yaml:"provider,omitempty"` // together/replicate/openrouter
}

LlamaConfig Meta Llama Provider 配置 (via Together AI/Replicate)

type MiniMaxConfig

type MiniMaxConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

MiniMaxConfig MiniMax Provider 配置

type MistralConfig

type MistralConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

MistralConfig Mistral AI Provider 配置

type OpenAICompatChoice

type OpenAICompatChoice struct {
	Index        int                  `json:"index"`
	FinishReason string               `json:"finish_reason"`
	Message      OpenAICompatMessage  `json:"message"`
	Delta        *OpenAICompatMessage `json:"delta,omitempty"`
}

OpenAICompatChoice 表示 OpenAI 兼容响应中的单个选项.

type OpenAICompatErrorResp

type OpenAICompatErrorResp struct {
	Error struct {
		Message string `json:"message"`
		Type    string `json:"type"`
		Code    any    `json:"code"`
		Param   string `json:"param"`
	} `json:"error"`
}

OpenAICompatErrorResp 表示 OpenAI 兼容的错误响应.

type OpenAICompatFunction

type OpenAICompatFunction struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

OpenAICompatFunction 表示 OpenAI 兼容的函数定义.

type OpenAICompatMessage

type OpenAICompatMessage struct {
	Role         string                 `json:"role"`
	Content      string                 `json:"content,omitempty"`
	MultiContent []map[string]any       `json:"multi_content,omitempty"` // multimodal content parts
	Name         string                 `json:"name,omitempty"`
	ToolCalls    []OpenAICompatToolCall `json:"tool_calls,omitempty"`
	ToolCallID   string                 `json:"tool_call_id,omitempty"`
}

OpenAICompatMessage 表示 OpenAI 兼容的消息格式.

func ConvertMessagesToOpenAI

func ConvertMessagesToOpenAI(msgs []llm.Message) []OpenAICompatMessage

ConvertMessagesToOpenAI 将 llm.Message 切片转换为 OpenAI 兼容格式.

func (OpenAICompatMessage) MarshalJSON added in v1.0.0

func (m OpenAICompatMessage) MarshalJSON() ([]byte, error)

MarshalJSON 自定义序列化:当 MultiContent 非空时,将其序列化为 "content" 字段。

type OpenAICompatRequest

type OpenAICompatRequest struct {
	Model          string                `json:"model"`
	Messages       []OpenAICompatMessage `json:"messages"`
	Tools          []OpenAICompatTool    `json:"tools,omitempty"`
	ToolChoice     any                   `json:"tool_choice,omitempty"`
	ResponseFormat any                   `json:"response_format,omitempty"`
	MaxTokens      int                   `json:"max_tokens,omitempty"`
	Temperature    float32               `json:"temperature,omitempty"`
	TopP           float32               `json:"top_p,omitempty"`
	Stop           []string              `json:"stop,omitempty"`
	Stream         bool                  `json:"stream,omitempty"`
}

OpenAICompatRequest 表示 OpenAI 兼容的聊天完成请求.

type OpenAICompatResponse

type OpenAICompatResponse struct {
	ID      string               `json:"id"`
	Model   string               `json:"model"`
	Choices []OpenAICompatChoice `json:"choices"`
	Usage   *OpenAICompatUsage   `json:"usage,omitempty"`
	Created int64                `json:"created,omitempty"`
}

OpenAICompatResponse 表示 OpenAI 兼容的聊天完成响应.

type OpenAICompatTool

type OpenAICompatTool struct {
	Type     string               `json:"type"`
	Function OpenAICompatFunction `json:"function"`
}

OpenAICompatTool 表示 OpenAI 兼容的工具定义.

func ConvertToolsToOpenAI

func ConvertToolsToOpenAI(tools []llm.ToolSchema) []OpenAICompatTool

ConvertToolsToOpenAI 将 llm.ToolSchema 切片转换为 OpenAI 兼容格式.

type OpenAICompatToolCall

type OpenAICompatToolCall struct {
	ID       string               `json:"id"`
	Type     string               `json:"type"`
	Function OpenAICompatFunction `json:"function"`
}

OpenAICompatToolCall 表示 OpenAI 兼容的工具调用.

type OpenAICompatUsage

type OpenAICompatUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

OpenAICompatUsage 表示 OpenAI 兼容响应中的 token 用量.

type OpenAIConfig

type OpenAIConfig struct {
	BaseProviderConfig `yaml:",inline"`
	Organization       string `json:"organization,omitempty" yaml:"organization,omitempty"`
	UseResponsesAPI    bool   `json:"use_responses_api,omitempty" yaml:"use_responses_api,omitempty"` // 启用新的 Responses API (2025)
}

OpenAIConfig OpenAI Provider 配置

type QwenConfig

type QwenConfig struct {
	BaseProviderConfig `yaml:",inline"`
}

QwenConfig Alibaba Qwen Provider 配置

type RetryConfig

type RetryConfig struct {
	MaxRetries    int           `json:"max_retries"`    // Maximum retry attempts, default 3
	InitialDelay  time.Duration `json:"initial_delay"`  // Initial backoff delay, default 1s
	MaxDelay      time.Duration `json:"max_delay"`      // Maximum backoff delay, default 30s
	BackoffFactor float64       `json:"backoff_factor"` // Exponential backoff factor, default 2.0
	RetryableOnly bool          `json:"retryable_only"` // Only retry errors marked Retryable
}

RetryConfig 持有提供者包装器的再试配置 。

func DefaultRetryConfig

func DefaultRetryConfig() RetryConfig

默认 RetriConfig 返回明智的重试默认 。

type RetryableProvider

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

可重试 Provider 包了 illm 。 提供指数后退的重试逻辑.

func NewRetryableProvider

func NewRetryableProvider(inner llm.Provider, config RetryConfig, logger *zap.Logger) *RetryableProvider

New Retryable Provider在给定的提供者周围创建了重试包.

func (*RetryableProvider) Completion

func (p *RetryableProvider) Completion(ctx context.Context, req *llm.ChatRequest) (*llm.ChatResponse, error)

Completion 执行聊天补全,在瞬态错误上重试.

func (*RetryableProvider) Endpoints added in v1.0.0

func (p *RetryableProvider) Endpoints() llm.ProviderEndpoints

func (*RetryableProvider) HealthCheck

func (p *RetryableProvider) HealthCheck(ctx context.Context) (*llm.HealthStatus, error)

func (*RetryableProvider) ListModels

func (p *RetryableProvider) ListModels(ctx context.Context) ([]llm.Model, error)

func (*RetryableProvider) Name

func (p *RetryableProvider) Name() string

func (*RetryableProvider) Stream

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

Stream 执行流式聊天请求,并重试连接错误. 只有连接建立阶段会被重试;流传输中的错误不会.

func (*RetryableProvider) SupportsNativeFunctionCalling

func (p *RetryableProvider) SupportsNativeFunctionCalling() bool

Directories

Path Synopsis
Package openaicompat provides a shared base implementation for all OpenAI-compatible LLM providers.
Package openaicompat provides a shared base implementation for all OpenAI-compatible LLM providers.
包 qwen 提供阿里巴巴通义千问(Qwen)系列模型的 Provider 适配实现, 基于 OpenAI 兼容协议接入 DashScope API。
包 qwen 提供阿里巴巴通义千问(Qwen)系列模型的 Provider 适配实现, 基于 OpenAI 兼容协议接入 DashScope API。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL