first commit

internal/llm/provider.go

@@ -0,0 +1,71 @@
+// Package llm 提供与 OpenAI 兼容接口的大模型通信能力（含视觉与流式）。
+package llm
+
+import (
+	"context"
+	"fmt"
+)
+
+// Role 是消息角色。
+type Role string
+
+// 支持的角色。
+const (
+	RoleUser      Role = "user"
+	RoleAssistant Role = "assistant"
+)
+
+// Message 是一条对话消息。Image 非空表示该消息附带一张 JPEG 图片。
+type Message struct {
+	Role  Role
+	Text  string
+	Image []byte
+}
+
+// Usage 记录一次调用的 token 用量。
+type Usage struct {
+	PromptTokens     int
+	CompletionTokens int
+	TotalTokens      int
+}
+
+// Add 累加用量。
+func (u *Usage) Add(o Usage) {
+	u.PromptTokens += o.PromptTokens
+	u.CompletionTokens += o.CompletionTokens
+	u.TotalTokens += o.TotalTokens
+}
+
+// DeltaFunc 接收流式增量文本，返回 error 可中断请求。
+type DeltaFunc func(delta string) error
+
+// Options 描述一个模型接入点。
+type Options struct {
+	Name         string
+	BaseURL      string
+	APIKey       string
+	Model        string
+	ExtraHeaders map[string]string
+	MaxTokens    int
+	Temperature  float64
+}
+
+// Provider 是大模型服务的最小抽象。
+// 目前只有 OpenAI 兼容实现，其它私有协议按此接口新增即可。
+type Provider interface {
+	// Chat 发起一次流式对话，system 为系统提示词。
+	Chat(ctx context.Context, system string, msgs []Message, fn DeltaFunc) (Usage, error)
+	// Ping 做一次最小代价的连通性检查。
+	Ping(ctx context.Context) error
+}
+
+// New 根据接入点创建 Provider。
+func New(opts Options) (Provider, error) {
+	if opts.BaseURL == "" {
+		return nil, fmt.Errorf("模型接入点缺少 BaseURL")
+	}
+	if opts.Model == "" {
+		return nil, fmt.Errorf("模型接入点 %s 缺少 model", opts.Name)
+	}
+	return newOpenAI(opts), nil
+}