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 ¶
- func BearerTokenHeaders(r *http.Request, apiKey string)
- func ChooseModel(req *llm.ChatRequest, defaultModel, fallbackModel string) string
- func ConvertResponseFormat(rf *llm.ResponseFormat) any
- func CreateEmbeddingOpenAICompat(ctx context.Context, client *http.Client, ...) (*llm.EmbeddingResponse, error)
- func GenerateAudioOpenAICompat(ctx context.Context, client *http.Client, ...) (*llm.AudioGenerationResponse, error)
- func GenerateImageOpenAICompat(ctx context.Context, client *http.Client, ...) (*llm.ImageGenerationResponse, error)
- func GenerateVideoOpenAICompat(ctx context.Context, client *http.Client, ...) (*llm.VideoGenerationResponse, error)
- func ListModelsOpenAICompat(ctx context.Context, client *http.Client, ...) ([]llm.Model, error)
- func MapHTTPError(status int, msg string, provider string) *llm.Error
- func NotSupportedError(providerName, feature string) *llm.Error
- func ReadErrorMessage(body io.Reader) string
- func SafeCloseBody(body io.ReadCloser)
- func ToLLMChatResponse(oa OpenAICompatResponse, provider string) *llm.ChatResponse
- type APIKeyEntry
- type BaseProviderConfig
- type ClaudeConfig
- type DeepSeekConfig
- type DoubaoConfig
- type GLMConfig
- type GeminiConfig
- type GrokConfig
- type HunyuanConfig
- type KimiConfig
- type LlamaConfig
- type MiniMaxConfig
- type MistralConfig
- type OpenAICompatChoice
- type OpenAICompatErrorResp
- type OpenAICompatFunction
- type OpenAICompatMessage
- type OpenAICompatRequest
- type OpenAICompatResponse
- type OpenAICompatTool
- type OpenAICompatToolCall
- type OpenAICompatUsage
- type OpenAIConfig
- type QwenConfig
- type RetryConfig
- type RetryableProvider
- func (p *RetryableProvider) Completion(ctx context.Context, req *llm.ChatRequest) (*llm.ChatResponse, error)
- func (p *RetryableProvider) Endpoints() llm.ProviderEndpoints
- func (p *RetryableProvider) HealthCheck(ctx context.Context) (*llm.HealthStatus, error)
- func (p *RetryableProvider) ListModels(ctx context.Context) ([]llm.Model, error)
- func (p *RetryableProvider) Name() string
- func (p *RetryableProvider) Stream(ctx context.Context, req *llm.ChatRequest) (<-chan llm.StreamChunk, error)
- func (p *RetryableProvider) SupportsNativeFunctionCalling() bool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BearerTokenHeaders ¶
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 ¶
MapHTTPError 将 HTTP 状态码映射为带有合适重试标记的 llm.Error 这是所有提供者使用的通用错误映射函数
func NotSupportedError ¶
NotSupportedError 返回不支持的错误
func ReadErrorMessage ¶
ReadErrorMessage 读取响应体中的错误消息 尝试解析 JSON 错误响应,失败则回退到原始文本
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 持有提供者包装器的再试配置 。
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 (*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。 |