Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

31.9 KB
Raw Blame
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later

package util

import (
	"bytes"
	"context"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"image"
	_ "image/gif"
	"image/jpeg"
	"image/png"
	"io"
	"maps"
	"net"
	"net/http"
	"net/netip"
	"net/url"
	"strconv"
	"strings"
	"sync"
	"syscall"
	"time"

	"github.com/disintegration/imaging"
	"github.com/gabriel-vasile/mimetype"
	"github.com/sashabaranov/go-openai"
	"github.com/siyuan-note/httpclient"
	"github.com/siyuan-note/logging"
	_ "golang.org/x/image/webp"
)

const (
	maxGeneratedImageBytes  = 50 * 1024 * 1024
	maxGeneratedImagePixels = 100 * 1000 * 1000
	maxModelContextLength   = 100 * 1000 * 1000
)

type PreparedImage struct {
	Data       []byte
	MIMEType   string
	Width      int
	Height     int
	SourceSize int
}

type GenerateImageRequest struct {
	Prompt       string
	Size         string
	Quality      string
	OutputFormat string
}

type GeneratedImage struct {
	Data          []byte
	MIMEType      string
	Extension     string
	RevisedPrompt string
}

type OpenAIImageAdapter struct {
	client  *openai.Client
	model   string
	timeout time.Duration
}

func ChatGPT(msg string, contextMsgs []string, c *AIClient, apiBaseURL, protocol, model string, maxTokens int,
	temperature float64, timeout int) (ret string, stop bool, err error) {
	var reqMsgs []openai.ChatCompletionMessage

	for _, ctxMsg := range contextMsgs {
		if "" == ctxMsg {
			continue
		}

		reqMsgs = append(reqMsgs, openai.ChatCompletionMessage{
			Role:    "user",
			Content: ctxMsg,
		})
	}

	if "" != msg {
		reqMsgs = append(reqMsgs, openai.ChatCompletionMessage{
			Role:    "user",
			Content: msg,
		})
	}

	if 1 > len(reqMsgs) {
		stop = true
		return
	}

	req := openai.ChatCompletionRequest{
		Model:               model,
		MaxCompletionTokens: maxTokens,
		Temperature:         float32(temperature),
		Messages:            reqMsgs,
	}
	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
	defer cancel()
	ctx = ContextWithOpenAIResponsesBaseURL(ctx, apiBaseURL)
	resp, err := CreateOpenAICompletion(ctx, c, protocol, req, nil)
	if err != nil {
		PushErrMsg("Requesting failed, please check kernel log for more details", 3000)
		logging.LogErrorf("create chat completion failed: %s", err)
		stop = true
		return
	}

	if 1 > len(resp.Choices) {
		stop = true
		return
	}

	buf := &strings.Builder{}
	choice := resp.Choices[0]
	buf.WriteString(choice.Message.Content)
	if "length" == choice.FinishReason {
		stop = false
	} else {
		stop = true
	}

	ret = buf.String()
	ret = strings.TrimSpace(ret)
	return
}

func NewOpenAIClient(apiKey, apiBaseURL string, headers ...map[string]string) *openai.Client {
	config := openai.DefaultConfig(apiKey)
	config.BaseURL = apiBaseURL
	config.HTTPClient = newAIProviderHTTPClient(apiBaseURL, headers...)
	return openai.NewClientWithConfig(config)
}

// builtinExtraBody 是「模型名前缀 → 额外请求参数」的内置适配清单。
// 仅收录参数语义为「纯输出格式开关」的模型(不改变思考行为、无副作用),
// 让这类模型从源头把推理内容拆到 reasoning_content 字段,而非以 <think> 标签混在 content 中。
// 其他模型由 agent.thinkSplitter 兜底解析 <think> 标签。
var builtinExtraBody = map[string]map[string]any{
	// MiniMax:开启 reasoning_split 后,thinking 内容拆到 reasoning_content 字段,
	// 不改变是否思考、无流式要求。覆盖 MiniMax-M* 和 abab* 两个命名族。
	"minimax-m": {"reasoning_split": true},
	"abab-":     {"reasoning_split": true},
}

// ExtraBodyForModel 按模型名大小写不敏感匹配内置清单,返回需注入的额外请求参数;无匹配返回 nil。
func ExtraBodyForModel(model string) map[string]any {
	lower := strings.ToLower(model)
	for prefix, extra := range builtinExtraBody {
		if strings.HasPrefix(lower, prefix) {
			return extra
		}
	}
	return nil
}

// extraBodyTransport 包装一个 HTTPDoer,在 chat/completions 请求体中注入额外字段。
// 利用 go-openai 在 client 层暴露的 HTTPDoer 扩展点(Chat 路径不支持 withExtraBody),
// 对流式与非流式 chat 请求都生效;非 chat 请求原样透传。
type extraBodyTransport struct {
	base      openai.HTTPDoer
	extraBody map[string]any
}

func (t *extraBodyTransport) Do(req *http.Request) (*http.Response, error) {
	if len(t.extraBody) == 0 || req.Method != http.MethodPost || !strings.Contains(req.URL.Path, "chat/completions") {
		return t.base.Do(req)
	}

	body, err := io.ReadAll(req.Body)
	if err != nil {
		return t.base.Do(req)
	}
	if err = req.Body.Close(); err != nil {
		return t.base.Do(req)
	}

	var payload map[string]any
	if err = json.Unmarshal(body, &payload); err != nil {
		// 请求体解析失败,用原始 body 透传,绝不破坏请求。
		req.Body = io.NopCloser(bytes.NewReader(body))
		req.ContentLength = int64(len(body))
		return t.base.Do(req)
	}

	maps.Copy(payload, t.extraBody)

	merged, err := json.Marshal(payload)
	if err != nil {
		req.Body = io.NopCloser(bytes.NewReader(body))
		req.ContentLength = int64(len(body))
		return t.base.Do(req)
	}

	req.Body = io.NopCloser(bytes.NewReader(merged))
	req.ContentLength = int64(len(merged))
	return t.base.Do(req)
}

// NewAIClientWithModel 创建生成客户端,并按模型与端点启用协议适配。
// 模型请求统一启用思考字段适配,命中清单的模型会注入额外参数,官方 Gemini 端点会保留工具调用签名。
func NewAIClientWithModel(apiKey, apiBaseURL, model string, headers ...map[string]string) *AIClient {
	extra := ExtraBodyForModel(model)
	geminiThoughtSignatures := isGoogleGeminiOpenAICompatibleEndpoint(apiBaseURL, model)
	config := openai.DefaultConfig(apiKey)
	config.BaseURL = apiBaseURL
	var transport openai.HTTPDoer = newAIProviderHTTPClient(apiBaseURL, headers...)
	if len(extra) > 0 {
		transport = &extraBodyTransport{base: transport, extraBody: extra}
	}
	if geminiThoughtSignatures {
		transport = WrapGeminiThoughtSignatureTransport(transport)
	}
	transport = &aiErrorResponseTransport{base: transport}
	transport = &reasoningResponseTransport{base: transport}
	config.HTTPClient = transport
	return &AIClient{Client: openai.NewClientWithConfig(config), baseURL: apiBaseURL,
		anthropicHTTP: newAnthropicHTTPClient(apiKey, apiBaseURL, headers...),
		geminiHTTP:    newGeminiInteractionsHTTPClient(apiKey, apiBaseURL, headers...)}
}

// TestModel 测试模型可用性。先按协议拉取可用模型清单,
// 再按 Provider 协议发送极简文本生成请求,确认所选协议实际可用。
// 返回值:available 为可用模型清单(仅 ListModels 成功时填充),matched 表示 model 是否可用,
// err 为请求错误(鉴权失败、网络异常、模型不存在等,原样返回便于调用方展示原因)。
func TestModel(apiKey, apiBaseURL, protocol, model string, timeout int, headers ...map[string]string) (available []string, matched bool, err error) {
	if 1 > timeout {
		timeout = 30
	}
	client := NewAIClientWithModel(apiKey, apiBaseURL, model, headers...)
	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
	defer cancel()
	ctx = ContextWithOpenAIResponsesBaseURL(ctx, apiBaseURL)

	// 优先校验模型是否在可用清单中
	var availableIDs []string
	var listErr error
	if IsAnthropicMessagesProtocol(protocol) || IsGeminiInteractionsProtocol(protocol) {
		var models []AvailableModel
		if IsGeminiInteractionsProtocol(protocol) {
			models, listErr = listGeminiInteractionModels(ctx, client)
		} else {
			models, listErr = listAnthropicModels(ctx, client)
		}
		for _, m := range models {
			availableIDs = append(availableIDs, m.ID)
		}
	} else {
		list, err := client.ListModels(ctx)
		listErr = err
		for _, m := range list.Models {
			availableIDs = append(availableIDs, m.ID)
		}
	}
	if nil == listErr {
		model = strings.TrimSpace(model)
		target := strings.ToLower(model)
		for _, id := range availableIDs {
			available = append(available, id)
			if strings.ToLower(id) == target {
				matched = true
			}
		}
		if !matched {
			logging.LogInfof("model [%s] not found in available list, test with text completion", model)
		}
	} else {
		// ListModels 不可用时仍使用极简文本生成请求验证连通性与鉴权。
		logging.LogInfof("list models failed [%s], test with text completion: %s", apiBaseURL, listErr)
	}

	messages := []openai.ChatCompletionMessage{{Role: "user", Content: "1"}}
	request := openai.ChatCompletionRequest{
		Model:               model,
		Messages:            messages,
		MaxCompletionTokens: 1,
		Temperature:         1,
	}
	if IsOpenAIResponsesProtocol(protocol) {
		// Responses 的输出预算至少为 16,包含可能使用的推理 token。
		request.MaxCompletionTokens = 16
	}
	if IsGeminiInteractionsProtocol(protocol) {
		// Gemini 的思考也消耗输出预算,为极简连通性测试保留有限预算。
		request.MaxCompletionTokens = 256
		request.ReasoningEffort = "low"
	}
	if IsOpenAIResponsesProtocol(protocol) || IsAnthropicMessagesProtocol(protocol) || IsGeminiInteractionsProtocol(protocol) {
		request.Stream = true
		var stream *OpenAICompletionStream
		stream, err = CreateOpenAICompletionStream(ctx, client, protocol, request, nil)
		if err == nil {
			defer stream.Close()
			for {
				_, receiveErr := stream.Recv()
				if errors.Is(receiveErr, io.EOF) {
					break
				}
				if receiveErr != nil {
					err = receiveErr
					break
				}
			}
		}
	} else {
		_, err = CreateOpenAICompletion(ctx, client, protocol, request, nil)
	}
	if IsGeminiInteractionsProtocol(protocol) && errors.Is(err, errGeminiInteractionIncomplete) {
		// 受限预算可能被思考耗尽,已校验的终止响应仍能证明协议连通;正常生成继续将不完整响应视为错误。
		err = nil
	}
	if nil != err {
		matched = false
		logging.LogErrorf("test model [%s] failed: %s", model, err)
		return
	}
	matched = true
	return
}

// TestEmbeddingModel 测试嵌入模型可用性,发送极简文本并返回首个向量维度。
// 返回值:matched 表示是否连通成功,dimensions 为返回的向量维度(便于核对配置),
// err 为请求错误(鉴权失败、网络异常、模型不存在等,原样返回便于调用方展示原因)。
func TestEmbeddingModel(apiKey, apiBaseURL, model string, dimensions, timeout int) (matched bool, dims int, err error) {
	if 1 > timeout {
		timeout = 30
	}
	client := NewOpenAIClient(apiKey, apiBaseURL)
	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
	defer cancel()

	// 用极简文本发一次 embedding 请求,验证连通性、鉴权与模型可用性
	resp, err := client.CreateEmbeddings(ctx, openai.EmbeddingRequestStrings{
		Input:      []string{"1"},
		Model:      openai.EmbeddingModel(model),
		Dimensions: dimensions, // 0 时因 omitempty 不发送,等同于用模型默认维度
	})
	if nil != err {
		logging.LogErrorf("test embedding model [%s] failed: %s", model, err)
		return
	}
	matched = true
	if 0 < len(resp.Data) {
		dims = len(resp.Data[0].Embedding)
	}
	return
}

type availableModelPayload struct {
	ID               string          `json:"id"`
	ContextLength    json.RawMessage `json:"context_length"`
	MaxContextLength json.RawMessage `json:"max_context_length"`
	MaxInputTokens   json.RawMessage `json:"max_input_tokens"`
}

type availableModelsPayload struct {
	Data []availableModelPayload `json:"data"`
}

// AvailableModel 描述 Provider 返回的模型及其可选上下文窗口。
type AvailableModel struct {
	ID            string
	ContextLength int
}

// ListAvailableModels 拉取 Provider 的可用模型清单(GET /v1/models),仅返回模型 ID 列表。
// 用于兼容不需要模型元数据的调用方。
func ListAvailableModels(apiKey, apiBaseURL string, timeout int) (models []string, err error) {
	metadata, err := ListAvailableModelsWithContext(apiKey, apiBaseURL, timeout)
	if err != nil {
		return nil, err
	}
	for _, model := range metadata {
		models = append(models, model.ID)
	}
	return
}

// ListAvailableModelsWithContext 拉取 Provider 的模型清单及可选上下文窗口。
// 通用 OpenAI 兼容接口不保证返回上下文长度,缺失或非法时保留模型并将 ContextLength 置为 0。
func ListAvailableModelsWithContext(apiKey, apiBaseURL string, timeout int, headers ...map[string]string) (models []AvailableModel, err error) {
	if 1 > timeout {
		timeout = 30
	}
	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
	defer cancel()

	endpoint := strings.TrimRight(apiBaseURL, "/") + "/models"
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
	if err != nil {
		return nil, err
	}
	if apiKey != "" {
		req.Header.Set("Authorization", "Bearer "+apiKey)
	}
	resp, err := newAIProviderHTTPClient(apiBaseURL, headers...).Do(req)
	if err != nil {
		logging.LogErrorf("list models [%s] failed: %s", apiBaseURL, err)
		return
	}
	defer resp.Body.Close()
	if resp.StatusCode < http.StatusOK || http.StatusBadRequest <= resp.StatusCode {
		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
		if readErr != nil {
			err = fmt.Errorf("list models HTTP %d", resp.StatusCode)
		} else {
			err = fmt.Errorf("list models HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
		}
		logging.LogErrorf("list models [%s] failed: %s", apiBaseURL, err)
		return
	}

	payload := &availableModelsPayload{}
	if err = json.NewDecoder(resp.Body).Decode(payload); err != nil {
		logging.LogErrorf("decode models [%s] failed: %s", apiBaseURL, err)
		return
	}
	for _, item := range payload.Data {
		id := strings.TrimSpace(item.ID)
		if id == "" {
			continue
		}
		models = append(models, AvailableModel{
			ID: id,
			ContextLength: firstValidModelContextLength(
				item.ContextLength,
				item.MaxContextLength,
				item.MaxInputTokens,
			),
		})
	}
	return
}

func firstValidModelContextLength(values ...json.RawMessage) int {
	for _, value := range values {
		if len(value) == 0 || value[0] == '"' {
			continue
		}
		parsed, err := strconv.ParseInt(strings.TrimSpace(string(value)), 10, 64)
		if err != nil || parsed < 1 || maxModelContextLength < parsed {
			continue
		}
		return int(parsed)
	}
	return 0
}

// embeddingHTTPClient 单例 HTTP 客户端,复用连接池并限制每主机最大连接数,
// 避免 embedding 索引器在 API 不可用时新建大量连接形成连接风暴。
// 单次请求超时由调用方用 context.WithTimeout 控制,client 本身不设全局 Timeout。
var (
	embeddingHTTPClientOnce sync.Once
	embeddingHTTPClient     *http.Client
	embeddingHTTPTransport  *http.Transport
	openAITransportMu       sync.Mutex
)

func getEmbeddingHTTPClient() *http.Client {
	embeddingHTTPClientOnce.Do(func() {
		transport := httpclient.NewTransport(false)
		transport.MaxConnsPerHost = 4 // 同一 embedding endpoint 的并发连接上限
		transport.MaxIdleConns = 8
		transport.MaxIdleConnsPerHost = 4
		transport.IdleConnTimeout = 90 * time.Second
		openAITransportMu.Lock()
		embeddingHTTPTransport = transport
		openAITransportMu.Unlock()
		embeddingHTTPClient = httpclient.NewUserAgentClient(transport)
	})
	return embeddingHTTPClient
}

func BatchGetEmbeddings(texts []string, apiKey, baseURL, model string, dimensions, timeout int) (ret [][]float32, err error) {
	if 1 > len(texts) {
		return
	}
	if timeout < 1 {
		timeout = 30
	}

	config := openai.DefaultConfig(apiKey)
	config.BaseURL = baseURL
	config.HTTPClient = getEmbeddingHTTPClient()
	client := openai.NewClientWithConfig(config)

	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
	defer cancel()

	request := openai.EmbeddingRequestStrings{
		Input:      texts,
		Model:      openai.EmbeddingModel(model),
		Dimensions: dimensions, // 0 时因 omitempty 不发送,等同于用模型默认维度
	}
	resp, err := client.CreateEmbeddings(ctx, request)
	if ctx.Err() == nil && retryableEmbeddingError(err) {
		// 嵌入计算遇到瞬时连接中断时最多补试一次,等待及补试共享原请求的超时预算。
		timer := time.NewTimer(200 * time.Millisecond)
		select {
		case <-ctx.Done():
			timer.Stop()
			err = ctx.Err()
		case <-timer.C:
			resp, err = client.CreateEmbeddings(ctx, request)
		}
	}
	if err != nil {
		logging.LogErrorf("create embeddings failed: %s", err)
		return
	}

	for _, data := range resp.Data {
		ret = append(ret, data.Embedding)
	}
	return
}

// retryableEmbeddingError 仅重试传输层连接中断,不重试接口状态错误、响应解析错误或超时。
func retryableEmbeddingError(err error) bool {
	var requestErr *url.Error
	if !errors.As(err, &requestErr) || requestErr.Timeout() {
		return false
	}
	return errors.Is(requestErr.Err, io.EOF) || errors.Is(requestErr.Err, io.ErrUnexpectedEOF) ||
		errors.Is(requestErr.Err, syscall.ECONNRESET) || errors.Is(requestErr.Err, syscall.EPIPE) ||
		requestErr.Err.Error() == "http: server closed idle connection"
}

// rerankDocTextMaxRunes 限制单篇文档送入重排服务的最大 Unicode 字符数,兼顾常见模型的输入上限。
const rerankDocTextMaxRunes = 4000

// rerankHTTPClient 单例 HTTP 客户端,复用连接池并限制每主机最大连接数,避免重排请求打满连接。
var (
	rerankHTTPClientOnce sync.Once
	rerankHTTPClient     *http.Client
	rerankHTTPTransport  *http.Transport
)

func getRerankHTTPClient() *http.Client {
	rerankHTTPClientOnce.Do(func() {
		transport := httpclient.NewTransport(false)
		transport.MaxConnsPerHost = 4
		transport.MaxIdleConns = 8
		transport.MaxIdleConnsPerHost = 4
		transport.IdleConnTimeout = 90 * time.Second
		openAITransportMu.Lock()
		rerankHTTPTransport = transport
		openAITransportMu.Unlock()
		rerankHTTPClient = httpclient.NewUserAgentClient(transport)
	})
	return rerankHTTPClient
}

func closeOpenAIIdleConnections() {
	openAITransportMu.Lock()
	defer openAITransportMu.Unlock()
	if embeddingHTTPTransport != nil {
		embeddingHTTPTransport.CloseIdleConnections()
	}
	if rerankHTTPTransport != nil {
		rerankHTTPTransport.CloseIdleConnections()
	}
}

type RerankRequestFormat string

const (
	RerankRequestFormatCohere    RerankRequestFormat = "cohere"
	RerankRequestFormatDashScope RerankRequestFormat = "dashscope"
)

type RerankOptions struct {
	APIKey        string
	Endpoint      string
	Model         string
	RequestFormat RerankRequestFormat
	TopN          int
	Timeout       int
}

// rerankCohereRequest 对应 Jina、Cohere 和阿里云 compatible-api 等服务的扁平请求体。
type rerankCohereRequest struct {
	Model     string   `json:"model"`
	Query     string   `json:"query"`
	Documents []string `json:"documents"`
	TopN      int      `json:"top_n,omitempty"`
}

type rerankDashScopeInput struct {
	Query     string   `json:"query"`
	Documents []string `json:"documents"`
}

type rerankDashScopeParameters struct {
	TopN int `json:"top_n"`
}

// rerankDashScopeRequest 对应 DashScope 和 ZenMux 等服务的嵌套请求体。
type rerankDashScopeRequest struct {
	Model      string                     `json:"model"`
	Input      rerankDashScopeInput       `json:"input"`
	Parameters *rerankDashScopeParameters `json:"parameters,omitempty"`
}

// rerankResult 为响应 results 数组中的单项,index 指向 documents 下标。
type rerankResult struct {
	Index          int     `json:"index"`
	RelevanceScore float64 `json:"relevance_score"`
}

// rerankResponse 对应 /v1/rerank 响应体。
type rerankResponse struct {
	Results []rerankResult `json:"results"`
	Output  *struct {
		Results []rerankResult `json:"results"`
	} `json:"output"`
}

// Rerank 调用重排服务对 query 与候选文档逐对精排。endpoint 为完整重排端点地址,不同服务商路径无统一标准
// (Jina /v1/rerank、阿里云 compatible-api/v1/reranks、Cohere /v1/rerank 等),由用户照文档填写。
// 返回的 indices 与 scores 均按 relevance_score 降序,indices 指向传入 documents 的下标。
// 对每条 document 文本按 rerankDocTextMaxRunes 截断,防超服务端 token 限制并保证 UTF-8 完整。
// topN 语义:topN <= 0 时不传 top_n(服务端默认返回全部文档评分,搜索场景用此避免被服务端 top_n 上限截断);
// topN > 0 时透传给服务端,仅用于测试连通性等只需少量结果的场景。
func Rerank(query string, documents []string, options RerankOptions) (indices []int, scores []float64, err error) {
	if 1 > options.Timeout {
		options.Timeout = 30
	}
	if 1 > len(documents) {
		return
	}
	if 0 < options.TopN && options.TopN > len(documents) {
		options.TopN = len(documents)
	}

	trimmed := make([]string, len(documents))
	for i, doc := range documents {
		trimmed[i] = truncateRerankDocument(doc)
	}

	body, err := marshalRerankRequest(query, trimmed, options)
	if nil != err {
		return
	}

	// endpoint 为完整重排端点地址,不做路径追加——不同服务商端点路径无统一标准,用户照文档填写。
	req, err := http.NewRequest(http.MethodPost, strings.TrimRight(options.Endpoint, "/"), bytes.NewReader(body))
	if nil != err {
		return
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+options.APIKey)

	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(options.Timeout)*time.Second)
	defer cancel()
	req = req.WithContext(ctx)

	resp, err := getRerankHTTPClient().Do(req)
	if nil != err {
		logging.LogErrorf("rerank request failed: %s", err)
		return
	}
	defer resp.Body.Close()

	respBody, err := io.ReadAll(resp.Body)
	if nil != err {
		return
	}
	if http.StatusOK != resp.StatusCode {
		err = fmt.Errorf("rerank HTTP %d: %s", resp.StatusCode, string(respBody))
		logging.LogErrorf("rerank failed: %s", err)
		return
	}

	var rr rerankResponse
	if err = json.Unmarshal(respBody, &rr); nil != err {
		return
	}

	results := rr.Results
	if nil == results && nil != rr.Output {
		results = rr.Output.Results
	}
	if nil == results {
		err = errors.New("rerank response missing results")
		return
	}

	for _, r := range results {
		if r.Index < 0 || r.Index >= len(documents) {
			continue
		}
		indices = append(indices, r.Index)
		scores = append(scores, r.RelevanceScore)
	}
	return
}

func marshalRerankRequest(query string, documents []string, options RerankOptions) ([]byte, error) {
	if RerankRequestFormatDashScope == options.RequestFormat {
		request := rerankDashScopeRequest{
			Model: options.Model,
			Input: rerankDashScopeInput{
				Query:     query,
				Documents: documents,
			},
		}
		if 0 < options.TopN {
			request.Parameters = &rerankDashScopeParameters{TopN: options.TopN}
		}
		return json.Marshal(request)
	}

	return json.Marshal(rerankCohereRequest{
		Model:     options.Model,
		Query:     query,
		Documents: documents,
		TopN:      options.TopN,
	})
}

func truncateRerankDocument(document string) string {
	runes := []rune(document)
	if len(runes) > rerankDocTextMaxRunes {
		return string(runes[:rerankDocTextMaxRunes])
	}
	return document
}

// TestRerankModel 测试重排模型可用性,用极简 query+documents 发一次重排请求验证连通性与鉴权。
// 返回值:matched 表示是否连通成功,err 为请求错误(鉴权失败、网络异常、模型不存在等,原样返回便于调用方展示原因)。
func TestRerankModel(options RerankOptions) (matched bool, err error) {
	documents := []string{"a", "b"}
	options.TopN = len(documents)
	indices, _, err := Rerank("1", documents, options)
	if nil != err {
		return
	}
	if len(indices) != len(documents) {
		err = fmt.Errorf("rerank returned %d indices for %d documents", len(indices), len(documents))
		return
	}
	seen := make(map[int]bool, len(indices))
	for _, index := range indices {
		if seen[index] {
			err = fmt.Errorf("rerank returned duplicate index %d", index)
			return
		}
		seen[index] = true
	}
	matched = true
	return
}

// PrepareModelImage 校验并按需缩放图片,尽量保留多模态模型支持的原始格式和图片质量。
func PrepareModelImage(data []byte, maxBytes, maxPixels, maxEdge int) (PreparedImage, error) {
	if len(data) == 0 {
		return PreparedImage{}, errors.New("image data is empty")
	}
	if maxBytes > 0 && len(data) > maxBytes {
		return PreparedImage{}, fmt.Errorf("image exceeds size limit: %d bytes", maxBytes)
	}
	mimeType := mimetype.Detect(data).String()
	if strings.Contains(mimeType, "svg") || bytes.Contains(bytes.ToLower(data[:min(len(data), 512)]), []byte("<svg")) {
		return PreparedImage{}, errors.New("SVG images are not accepted by multimodal models")
	}
	switch mimeType {
	case "image/gif", "image/jpeg", "image/png", "image/webp":
	default:
		return PreparedImage{}, fmt.Errorf("unsupported image type: %s", mimeType)
	}
	config, _, err := image.DecodeConfig(bytes.NewReader(data))
	if err != nil {
		return PreparedImage{}, errors.New("unsupported or invalid image: " + err.Error())
	}
	if config.Width < 1 || config.Height < 1 || maxPixels > 0 && int64(config.Width)*int64(config.Height) > int64(maxPixels) {
		return PreparedImage{}, fmt.Errorf("image exceeds pixel limit: %d", maxPixels)
	}

	decoded, err := imaging.Decode(bytes.NewReader(data), imaging.AutoOrientation(true))
	if err != nil {
		return PreparedImage{}, errors.New("decode image failed: " + err.Error())
	}
	bounds := decoded.Bounds()
	needsResize := maxEdge > 0 && (bounds.Dx() > maxEdge || bounds.Dy() > maxEdge)
	if !needsResize && bounds.Dx() == config.Width && bounds.Dy() == config.Height && mimeType != "image/gif" {
		return PreparedImage{
			Data:       data,
			MIMEType:   mimeType,
			Width:      bounds.Dx(),
			Height:     bounds.Dy(),
			SourceSize: len(data),
		}, nil
	}
	if needsResize {
		decoded = imaging.Fit(decoded, maxEdge, maxEdge, imaging.Lanczos)
	}
	bounds = decoded.Bounds()
	if mimeType == "image/png" || mimeType == "image/webp" {
		var output bytes.Buffer
		if err = png.Encode(&output, decoded); err != nil {
			return PreparedImage{}, errors.New("encode image failed: " + err.Error())
		}
		if maxBytes <= 0 || output.Len() <= maxBytes {
			return PreparedImage{
				Data:       output.Bytes(),
				MIMEType:   "image/png",
				Width:      bounds.Dx(),
				Height:     bounds.Dy(),
				SourceSize: len(data),
			}, nil
		}
	}
	var output bytes.Buffer
	if err = jpeg.Encode(&output, decoded, &jpeg.Options{Quality: 92}); err != nil {
		return PreparedImage{}, errors.New("encode image failed: " + err.Error())
	}
	if maxBytes > 0 && output.Len() > maxBytes {
		return PreparedImage{}, fmt.Errorf("prepared image exceeds size limit: %d bytes", maxBytes)
	}
	return PreparedImage{
		Data:       output.Bytes(),
		MIMEType:   "image/jpeg",
		Width:      bounds.Dx(),
		Height:     bounds.Dy(),
		SourceSize: len(data),
	}, nil
}

// ValidateGeneratedImage 校验生成图片的格式、尺寸和体积。
func ValidateGeneratedImage(data []byte) (mimeType, extension string, err error) {
	if len(data) == 0 {
		return "", "", errors.New("generated image is empty")
	}
	if len(data) > maxGeneratedImageBytes {
		return "", "", errors.New("generated image exceeds size limit")
	}
	mimeType = mimetype.Detect(data).String()
	switch mimeType {
	case "image/png":
		extension = ".png"
	case "image/jpeg":
		extension = ".jpg"
	case "image/webp":
		extension = ".webp"
	default:
		return "", "", fmt.Errorf("unsupported generated image type: %s", mimeType)
	}
	config, _, decodeErr := image.DecodeConfig(bytes.NewReader(data))
	if decodeErr != nil || config.Width < 1 || config.Height < 1 || config.Width > 16384 || config.Height > 16384 ||
		int64(config.Width)*int64(config.Height) > maxGeneratedImagePixels {
		return "", "", errors.New("generated image is invalid")
	}
	return mimeType, extension, nil
}

func NewOpenAIImageAdapter(apiKey, apiBaseURL, model string, timeout int, headers ...map[string]string) *OpenAIImageAdapter {
	if timeout < 1 {
		timeout = 30
	}
	client := NewAIClientWithModel(apiKey, apiBaseURL, model, headers...).Client
	if isMiniMaxImageEndpoint(apiBaseURL) {
		config := openai.DefaultConfig(apiKey)
		config.BaseURL = apiBaseURL
		config.HTTPClient = &miniMaxImageTransport{base: newAIProviderHTTPClient(apiBaseURL, headers...)}
		client = openai.NewClientWithConfig(config)
	}
	return &OpenAIImageAdapter{
		client:  client,
		model:   model,
		timeout: time.Duration(timeout) * time.Second,
	}
}

func (adapter *OpenAIImageAdapter) Generate(ctx context.Context, request GenerateImageRequest) (GeneratedImage, error) {
	if strings.TrimSpace(request.Prompt) == "" {
		return GeneratedImage{}, errors.New("image prompt is required")
	}
	imageRequest := openai.ImageRequest{
		Prompt:  request.Prompt,
		Model:   adapter.model,
		N:       1,
		Size:    request.Size,
		Quality: request.Quality,
	}
	if strings.HasPrefix(strings.ToLower(adapter.model), "dall-e") {
		imageRequest.ResponseFormat = openai.CreateImageResponseFormatB64JSON
		if imageRequest.Quality == "auto" {
			imageRequest.Quality = ""
		}
	} else {
		imageRequest.OutputFormat = request.OutputFormat
	}
	requestCtx, cancel := context.WithTimeout(ctx, adapter.timeout)
	defer cancel()
	response, err := adapter.client.CreateImage(requestCtx, imageRequest)
	if err != nil {
		return GeneratedImage{}, err
	}
	if len(response.Data) == 0 {
		return GeneratedImage{}, errors.New("image model returned no image")
	}
	result := response.Data[0]
	var data []byte
	if result.B64JSON != "" {
		data, err = base64.StdEncoding.DecodeString(result.B64JSON)
	} else if result.URL != "" {
		data, err = downloadGeneratedImage(requestCtx, result.URL)
	} else {
		err = errors.New("image model returned neither base64 data nor URL")
	}
	if err != nil {
		return GeneratedImage{}, err
	}
	mimeType, extension, err := ValidateGeneratedImage(data)
	if err != nil {
		return GeneratedImage{}, err
	}
	return GeneratedImage{Data: data, MIMEType: mimeType, Extension: extension, RevisedPrompt: result.RevisedPrompt}, nil
}

func downloadGeneratedImage(ctx context.Context, rawURL string) ([]byte, error) {
	parsed, err := url.Parse(rawURL)
	if err != nil || parsed.Scheme != "https" || parsed.Host == "" {
		return nil, errors.New("generated image URL must use HTTPS")
	}
	if err = CheckHostSSRF(parsed.Hostname()); err != nil {
		return nil, err
	}
	client := generatedImageHTTPClient()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
	if err != nil {
		return nil, err
	}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		return nil, fmt.Errorf("download generated image failed with status %d", resp.StatusCode)
	}
	if resp.ContentLength > maxGeneratedImageBytes {
		return nil, errors.New("generated image exceeds size limit")
	}
	data, err := io.ReadAll(io.LimitReader(resp.Body, maxGeneratedImageBytes+1))
	if err != nil {
		return nil, err
	}
	if len(data) > maxGeneratedImageBytes {
		return nil, errors.New("generated image exceeds size limit")
	}
	return data, nil
}

func generatedImageHTTPClient() *http.Client {
	return &http.Client{
		Transport: &http.Transport{
			Proxy:       httpclient.ProxyFromEnvironment,
			DialContext: generatedImageDialer().DialContext,
		},
		CheckRedirect: func(req *http.Request, via []*http.Request) error {
			if len(via) >= 3 || req.URL.Scheme != "https" {
				return errors.New("generated image redirect is not allowed")
			}
			return CheckHostSSRF(req.URL.Hostname())
		},
	}
}

func generatedImageDialer() *net.Dialer {
	return &net.Dialer{
		Timeout: 30 * time.Second,
		Control: func(_, address string, _ syscall.RawConn) error {
			host, _, err := net.SplitHostPort(address)
			if err != nil {
				return err
			}
			ip, parseErr := netip.ParseAddr(host)
			if parseErr != nil || isUnsafeGeneratedImageIP(ip.Unmap()) {
				return errors.New("generated image URL resolved to a private or invalid IP")
			}
			return nil
		},
	}
}

func isUnsafeGeneratedImageIP(ip netip.Addr) bool {
	if !ip.IsValid() || !ip.IsGlobalUnicast() || ip.IsPrivate() || ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsUnspecified() {
		return true
	}
	// IsPrivate 不包含共享地址空间和基准测试网段,这些地址仍可能指向本地基础设施。
	for _, prefix := range []netip.Prefix{
		netip.MustParsePrefix("100.64.0.0/10"),
		netip.MustParsePrefix("198.18.0.0/15"),
	} {
		if prefix.Contains(ip) {
			return true
		}
	}
	return false
}