openaiclient

package
v1.0.178 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ResponsesItemMessage        = "message"
	ResponsesItemFunctionCall   = "function_call"
	ResponsesItemFunctionOutput = "function_call_output"
	ResponsesItemReasoning      = "reasoning"
	ResponsesPartInputText      = "input_text"
	ResponsesPartOutputText     = "output_text"
	ResponsesPartRefusal        = "refusal"
	ResponsesPartSummaryText    = "summary_text"
)

Responses API wire vocabulary.

View Source
const (
	DefaultBaseURL              = "https://api.openai.com/v1"
	DefaultFunctionCallBehavior = "auto"
	DefaultChatModel            = "gpt-5-mini"
	DefaultMaxTokens            = 2 * 16384
)

Variables

View Source
var ErrContentExclusive = errors.New("only one of Content / MultiContent allowed in message")
View Source
var ErrEmptyResponse = errors.New("empty response")

ErrEmptyResponse is returned when the OpenAI API returns an empty response.

Functions

func ErrBatchUnsupported added in v0.17.130

func ErrBatchUnsupported() error

ErrBatchUnsupported is the package-level sentinel exposed for upstream callers that want to detect "provider does not support batching".

func IsAzure

func IsAzure(apiType ProviderType) bool

func IsBedrock added in v0.19.148

func IsBedrock(apiType ProviderType) bool

Types

type BatchCreateParams added in v0.17.130

type BatchCreateParams struct {
	// InputFileID is the file_id returned by UploadBatchFile.
	InputFileID string
	// Endpoint is the OpenAI URL path used by every request in the batch.
	Endpoint BatchEndpoint
	// CompletionWindow is the maximum time the batch may run. Currently only
	// "24h" is accepted by the API; empty defaults to "24h".
	CompletionWindow string
	// Metadata is round-tripped through the API on the batch object.
	Metadata map[string]string
}

BatchCreateParams is the input to CreateBatch.

type BatchEndpoint added in v0.17.130

type BatchEndpoint string

BatchEndpoint is the OpenAI URL path used by every request in a batch.

const (
	// EndpointChatCompletions targets the /v1/chat/completions endpoint.
	EndpointChatCompletions BatchEndpoint = "/v1/chat/completions"
	// EndpointResponses targets the /v1/responses endpoint.
	EndpointResponses BatchEndpoint = "/v1/responses"
)

type ChatCompletionChoice

type ChatCompletionChoice struct {
	Index        int          `json:"index"`
	Message      ChatMessage  `json:"message"`
	FinishReason FinishReason `json:"finish_reason"`
	LogProbs     *LogProbs    `json:"logprobs,omitempty"`
}

ChatCompletionChoice is a choice in a chat response.

type ChatCompletionResponse

type ChatCompletionResponse struct {
	ID                string                  `json:"id,omitempty"`
	Created           int64                   `json:"created,omitempty"`
	Choices           []*ChatCompletionChoice `json:"choices,omitempty"`
	Model             string                  `json:"model,omitempty"`
	Object            string                  `json:"object,omitempty"`
	Usage             ChatUsage               `json:"usage,omitempty"`
	SystemFingerprint string                  `json:"system_fingerprint"`
}

ChatCompletionResponse is a response to a chat request.

type ChatMessage

type ChatMessage struct {
	// The role of the author of this message. One of system, user, assistant, function, or tool.
	Role string

	// The content of the message.
	// This field is mutually exclusive with MultiContent.
	Content string

	// MultiContent is a list of content parts to use in the message.
	MultiContent []llms.ContentPart

	// The name of the author of this message. May contain a-z, A-Z, 0-9, and underscores,
	// with a maximum length of 64 characters.
	Name string

	// ToolCalls is a list of tools that were called in the message.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// ToolCallID is the ID of the tool call this message is for.
	// Only present in tool messages.
	ToolCallID string `json:"tool_call_id,omitempty"`

	// This field is only used with the deepseek-reasoner model and represents the reasoning contents of the assistant message before the final answer.
	ReasoningContent string `json:"reasoning_content,omitempty"`
}

ChatMessage is a message in a chat request.

func (ChatMessage) MarshalJSON

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

func (*ChatMessage) UnmarshalJSON

func (m *ChatMessage) UnmarshalJSON(data []byte) error

type ChatRequest

type ChatRequest struct {
	Model               string         `json:"model"`
	Messages            []*ChatMessage `json:"messages"`
	Temperature         float64        `json:"temperature"`
	TopP                float64        `json:"top_p,omitempty"`
	MaxCompletionTokens int            `json:"max_completion_tokens,omitempty"`
	N                   int            `json:"n,omitempty"`
	StopWords           []string       `json:"stop,omitempty"`
	Stream              bool           `json:"stream,omitempty"`
	FrequencyPenalty    float64        `json:"frequency_penalty,omitempty"`
	PresencePenalty     float64        `json:"presence_penalty,omitempty"`
	Seed                int            `json:"seed,omitempty"`
	// ReasoningEffort is the reasoning effort for models that have such a
	// control. Empty leaves the model's own default in place.
	ReasoningEffort string `json:"reasoning_effort,omitempty"`

	// ResponseFormat is the format of the response.
	ResponseFormat *schema.ResponseFormat `json:"response_format,omitempty"`

	// LogProbs indicates whether to return log probabilities of the output tokens or not.
	// If true, returns the log probabilities of each output token returned in the content of message.
	// This option is currently not available on the gpt-4-vision-preview model.
	LogProbs bool `json:"logprobs,omitempty"`
	// TopLogProbs is an integer between 0 and 5 specifying the number of most likely tokens to return at each
	// token position, each with an associated log probability.
	// logprobs must be set to true if this parameter is used.
	TopLogProbs int `json:"top_logprobs,omitempty"`

	Tools []Tool `json:"tools,omitempty"`
	// This can be either a string or a ToolChoice object.
	// If it is a string, it should be one of 'none', or 'auto', otherwise it should be a ToolChoice object specifying a specific tool to use.
	ToolChoice any `json:"tool_choice,omitempty"`

	// Options for streaming response. Only set this when you set stream: true.
	StreamOptions *StreamOptions `json:"stream_options,omitempty"`

	// StreamingFunc is a function to be called for each chunk of a streaming response.
	// Return an error to stop streaming early.
	StreamingFunc func(ctx context.Context, chunk []byte) error `json:"-"`

	// StreamingReasoningFunc is a function to be called for each reasoning and content chunk of a streaming response.
	// Return an error to stop streaming early.
	StreamingReasoningFunc func(ctx context.Context, reasoningChunk, chunk []byte) error `json:"-"`

	// Metadata allows you to specify additional information that will be passed to the model.
	Metadata map[string]any `json:"metadata,omitempty"`

	// PromptCacheKey identifies a cached prompt on providers that support prompt caching.
	PromptCacheKey string `json:"prompt_cache_key,omitempty"`
	// PromptCacheRetention controls request-level prompt cache retention.
	PromptCacheRetention string `json:"prompt_cache_retention,omitempty"`
}

ChatRequest is a request to complete a chat completion..

type ChatUsage

type ChatUsage struct {
	PromptTokens            int `json:"prompt_tokens"`
	CompletionTokens        int `json:"completion_tokens"`
	TotalTokens             int `json:"total_tokens"`
	CompletionTokensDetails struct {
		ReasoningTokens int `json:"reasoning_tokens"`
	} `json:"completion_tokens_details"`
}

ChatUsage is the usage of a chat completion request.

type Client

type Client struct {
	Model    string
	Provider ProviderType

	EmbeddingModel string

	ResponseFormat *schema.ResponseFormat
	// contains filtered or unexported fields
}

Client is a client for the OpenAI API.

func New

func New(provider ProviderType, model string, token string, baseURL string, organization, project string,
	apiVersion string, httpClient Doer, embeddingModel string,
	responseFormat *schema.ResponseFormat, headers map[string]string,
	opts ...Option,
) (*Client, error)

New returns a new OpenAI client.

func (*Client) CancelBatch added in v0.17.130

func (c *Client) CancelBatch(ctx context.Context, batchID string) (*openaisdk.Batch, error)

CancelBatch requests cancellation of an in-flight batch.

func (*Client) CreateBatch added in v0.17.130

func (c *Client) CreateBatch(ctx context.Context, params BatchCreateParams) (*openaisdk.Batch, error)

CreateBatch creates a new batch from a previously uploaded input file.

func (*Client) CreateChat

func (c *Client) CreateChat(ctx context.Context, r *ChatRequest) (*ChatCompletionResponse, error)

CreateChat creates chat request.

func (*Client) CreateCompletion

func (c *Client) CreateCompletion(ctx context.Context, r *CompletionRequest) (*Completion, error)

CreateCompletion creates a completion.

func (*Client) CreateEmbedding

func (c *Client) CreateEmbedding(ctx context.Context, r *EmbeddingRequest) ([][]float32, error)

CreateEmbedding creates embeddings.

func (*Client) CreateResponse added in v0.14.88

func (c *Client) CreateResponse(ctx context.Context, r *responses.ResponseNewParams) (*responses.Response, error)

CreateResponse creates a response using the Responses API.

func (*Client) CreateStreamingResponse added in v0.15.112

func (c *Client) CreateStreamingResponse(
	ctx context.Context,
	r *responses.ResponseNewParams,
	streamFunc func(ctx context.Context, chunk []byte) error,
) (*responses.Response, error)

CreateStreamingResponse creates a response using the Responses API with SSE streaming. streamFunc is called for each text delta chunk. The full Response (with usage stats) is returned once the response.completed event is received.

func (*Client) DownloadFile added in v0.17.130

func (c *Client) DownloadFile(ctx context.Context, fileID string) (io.ReadCloser, error)

DownloadFile streams the raw contents of a file (typically a batch output or error file). The caller is responsible for closing the returned reader.

func (*Client) GetBatch added in v0.17.130

func (c *Client) GetBatch(ctx context.Context, batchID string) (*openaisdk.Batch, error)

GetBatch retrieves the current state of a submitted batch.

func (*Client) InferChat added in v0.21.160

func (c *Client) InferChat(ctx context.Context, body map[string]any) (*llms.InferenceResponse, error)

InferChat performs one non-streaming Chat Completions call with the raw body supplied by the connector, using the shared authenticated SDK transport and no retries. Legacy defaults are not changed.

func (*Client) InferResponses added in v0.21.160

func (c *Client) InferResponses(ctx context.Context, body map[string]any) (*llms.InferenceResponse, error)

InferResponses performs one non-streaming Responses API call with the raw body supplied by the connector, using the shared authenticated SDK transport and no retries. Reasoning items are returned with their raw JSON as opaque state.

func (*Client) ListModels added in v1.0.173

func (c *Client) ListModels(ctx context.Context) ([]llms.ModelInfo, error)

ListModels returns the models the provider lists for the account, in the provider's order. It reads the fields of the OpenAI list, and the extra ones of the OpenRouter list when they are present:

shutdown_date, expiration_date   a date makes the model deprecated,
                                 null makes it active
name                             the display name
reasoning.supported_efforts      the reasoning effort levels
reasoning.default_effort         the level applied when none is named

A reasoning level without a portable name, such as "minimal", is left out.

Neither API pages its list today. A list that says it holds more models than it returned is an error, because a truncated list would make models look retired.

func (*Client) SupportsResponsesAPI added in v0.14.88

func (c *Client) SupportsResponsesAPI() bool

func (*Client) UploadBatchFile added in v0.17.130

func (c *Client) UploadBatchFile(ctx context.Context, name string, body io.Reader) (string, error)

UploadBatchFile uploads a JSONL file with purpose=batch and returns the file ID that should be passed to CreateBatch. The caller is responsible for formatting body as a JSONL document where each line is a valid batch request.

type Completion

type Completion struct {
	Text string `json:"text"`
}

Completion is a completion.

type CompletionRequest

type CompletionRequest struct {
	Model               string   `json:"model"`
	Prompt              string   `json:"prompt"`
	Temperature         float64  `json:"temperature"`
	MaxCompletionTokens int      `json:"max_completion_tokens,omitempty"`
	N                   int      `json:"n,omitempty"`
	FrequencyPenalty    float64  `json:"frequency_penalty,omitempty"`
	PresencePenalty     float64  `json:"presence_penalty,omitempty"`
	TopP                float64  `json:"top_p,omitempty"`
	StopWords           []string `json:"stop,omitempty"`
	Seed                int      `json:"seed,omitempty"`

	// StreamingFunc is a function to be called for each chunk of a streaming response.
	// Return an error to stop streaming early.
	StreamingFunc func(ctx context.Context, chunk []byte) error `json:"-"`
}

CompletionRequest is a request to complete a completion.

type CompletionResponse

type CompletionResponse struct {
	ID      string  `json:"id,omitempty"`
	Created float64 `json:"created,omitempty"`
	Choices []struct {
		FinishReason string  `json:"finish_reason,omitempty"`
		Index        float64 `json:"index,omitempty"`
		Logprobs     any     `json:"logprobs,omitempty"`
		Text         string  `json:"text,omitempty"`
	} `json:"choices,omitempty"`
	Model  string `json:"model,omitempty"`
	Object string `json:"object,omitempty"`
	Usage  struct {
		CompletionTokens float64 `json:"completion_tokens,omitempty"`
		PromptTokens     float64 `json:"prompt_tokens,omitempty"`
		TotalTokens      float64 `json:"total_tokens,omitempty"`
	} `json:"usage,omitempty"`
}

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer performs a HTTP request.

type EmbeddingRequest

type EmbeddingRequest struct {
	Model string   `json:"model"`
	Input []string `json:"input"`
}

EmbeddingRequest is a request to create an embedding.

type FinishReason

type FinishReason string
const (
	FinishReasonStop          FinishReason = "stop"
	FinishReasonLength        FinishReason = "length"
	FinishReasonFunctionCall  FinishReason = "function_call"
	FinishReasonToolCalls     FinishReason = "tool_calls"
	FinishReasonContentFilter FinishReason = "content_filter"
	FinishReasonNull          FinishReason = "null"
)

func (FinishReason) MarshalJSON

func (r FinishReason) MarshalJSON() ([]byte, error)

type FunctionCall

type FunctionCall struct {
	// Name is the name of the function to call.
	Name string `json:"name"`
	// Arguments is the set of arguments to pass to the function.
	Arguments string `json:"arguments"`
}

FunctionCall is a call to a function.

type FunctionCallBehavior

type FunctionCallBehavior string

FunctionCallBehavior is the behavior to use when calling functions.

const (
	// FunctionCallBehaviorUnspecified is the empty string.
	FunctionCallBehaviorUnspecified FunctionCallBehavior = ""
	// FunctionCallBehaviorNone will not call any functions.
	FunctionCallBehaviorNone FunctionCallBehavior = "none"
	// FunctionCallBehaviorAuto will call functions automatically.
	FunctionCallBehaviorAuto FunctionCallBehavior = "auto"
)

type FunctionDefinition

type FunctionDefinition struct {
	// Name is the name of the function.
	Name string `json:"name"`
	// Description is a description of the function.
	Description string `json:"description,omitempty"`
	// Parameters is the JSON Schema of the function arguments. Nil leaves
	// it out of the request: the function takes no arguments.
	Parameters any `json:"parameters,omitempty"`
	// Strict is a flag to enable structured output mode.
	Strict bool `json:"strict,omitempty"`
}

FunctionDefinition is a definition of a function that can be called by the model.

type LogProb

type LogProb struct {
	Token   string  `json:"token"`
	LogProb float64 `json:"logprob"`
	Bytes   []byte  `json:"bytes,omitempty"` // Omitting the field if it is null
	// TopLogProbs is a list of the most likely tokens and their log probability, at this token position.
	// In rare cases, there may be fewer than the number of requested top_logprobs returned.
	TopLogProbs []TopLogProbs `json:"top_logprobs"`
}

LogProb represents the probability information for a token.

type LogProbs

type LogProbs struct {
	// Content is a list of message content tokens with log probability information.
	Content []LogProb `json:"content"`
}

LogProbs is the top-level structure containing the log probability information.

type Option

type Option func(*Client) error

Option is an option for the OpenAI client.

type ProviderType added in v0.14.88

type ProviderType string
const (
	ProviderOpenAI        ProviderType = "OPENAI"
	ProviderOpenAIBedrock ProviderType = "OPENAI_BEDROCK"
	ProviderOpenRouter    ProviderType = "OPENROUTER"
	ProviderAzure         ProviderType = "AZURE"
	ProviderAzureAD       ProviderType = "AZURE_AD"
)

type StreamOptions

type StreamOptions struct {
	// If set, an additional chunk will be streamed before the data: [DONE] message.
	// The usage field on this chunk shows the token usage statistics for the entire request,
	// and the choices field will always be an empty array.
	// All other chunks will also include a usage field, but with a null value.
	IncludeUsage bool `json:"include_usage,omitempty"`
}

type StreamedChatResponsePayload

type StreamedChatResponsePayload struct {
	ID      string  `json:"id,omitempty"`
	Created float64 `json:"created,omitempty"`
	Model   string  `json:"model,omitempty"`
	Object  string  `json:"object,omitempty"`
	Choices []struct {
		Index float64 `json:"index,omitempty"`
		Delta struct {
			Role    string `json:"role,omitempty"`
			Content string `json:"content,omitempty"`
			// ToolCalls is a list of tools that were called in the message.
			ToolCalls []*ToolCall `json:"tool_calls,omitempty"`
			// This field is only used with the deepseek-reasoner model and represents the reasoning contents of the assistant message before the final answer.
			ReasoningContent string `json:"reasoning_content,omitempty"`
		} `json:"delta,omitempty"`
		FinishReason FinishReason `json:"finish_reason,omitempty"`
	} `json:"choices,omitempty"`
	SystemFingerprint string `json:"system_fingerprint"`
	// An optional field that will only be present when you set stream_options: {"include_usage": true} in your request.
	// When present, it contains a null value except for the last chunk which contains the token usage statistics
	// for the entire request.
	Usage *Usage `json:"usage,omitempty"`
	Error error  `json:"-"` // use for error handling only
}

StreamedChatResponsePayload is a chunk from the stream.

type Tool

type Tool struct {
	Type     ToolType            `json:"type"`
	Function *FunctionDefinition `json:"function,omitempty"`
	// For tools like web_search, you can include extra options.
	WebSearchOptions *WebSearchOptions `json:"-"`
}

Tool is a tool to use in a chat request.

func (Tool) MarshalJSON added in v0.14.88

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

type ToolCall

type ToolCall struct {
	ID       string       `json:"id,omitempty"`
	Type     ToolType     `json:"type"`
	Function ToolFunction `json:"function,omitempty"`
}

ToolCall is a call to a tool.

func StreamingChatResponseTools

func StreamingChatResponseTools(tools []ToolCall, delta []*ToolCall) ([]byte, []ToolCall)

StreamingChatResponseTools is a helper function to append tool calls to the stack.

type ToolChoice

type ToolChoice struct {
	Type     ToolType     `json:"type"`
	Function ToolFunction `json:"function,omitempty"`
}

ToolChoice is a choice of a tool to use.

type ToolFunction

type ToolFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ToolFunction is a function to be called in a tool choice.

type ToolType

type ToolType string

ToolType is the type of a tool.

const (
	ToolTypeFunction  ToolType = "function"
	ToolTypeWebSearch ToolType = "web_search"
)

type TopLogProbs

type TopLogProbs struct {
	Token   string  `json:"token"`
	LogProb float64 `json:"logprob"`
	Bytes   []byte  `json:"bytes,omitempty"`
}

type Usage

type Usage struct {
	PromptTokens            int `json:"prompt_tokens"`
	CompletionTokens        int `json:"completion_tokens"`
	TotalTokens             int `json:"total_tokens"`
	CompletionTokensDetails struct {
		ReasoningTokens int `json:"reasoning_tokens"`
	} `json:"completion_tokens_details"`
}

type WebSearchOptions added in v0.14.88

type WebSearchOptions struct {
	AllowedDomains []string
}

Jump to

Keyboard shortcuts

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