deepseek

package
v0.1.7 Latest Latest
Warning

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

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

Documentation

Overview

Package deepseek is the api.Provider for DeepSeek's Chat Completions API.

Build one with New and pass it to neui.WithProvider as the app-wide provider, or to neui.OptionProvider to set one session's provider, which takes precedence over WithProvider if any:

p, err := deepseek.New(deepseek.Conf{Model: deepseek.Flash},
	deepseek.WithEffort(deepseek.EffortMax))

The key comes from DEEPSEEK_API_KEY unless WithAPIKey sets it. A provider serves one model with one set of options; build two for two settings. For a model declared here New refuses a setting DeepSeek would reject or ignore, so a Provider that was built sends what it was given; for any other model it checks no combination and every option is sent as configured. Thinking is on by default and streams back as readable reasoning. Images go to deepseek-flash in user messages and tool results; every other model gets a short note in place of each image, and every model gets one in place of a document. Caching is automatic and needs no options: keep the tools, system prompt and history stable between turns to hit it. Failures reach the thread as api.EventErr with an api.ErrCode. Its Err is an *APIError for a non 200 response, a *RequestError for a request this adapter refused to encode, a *FinishError for a finish_reason that ended the turn without a reply, and a *StreamError for an error frame in the stream; read them with errors.As.

Index

Constants

View Source
const Name = "deepseek"

Name is what Provider.Name returns.

Variables

View Source
var (
	Flash = api.Model{Name: "deepseek-flash", Context: 1_048_576, ImagePixels: 1300 * 1300, ImageSide: 8192, ImageBytes: 24 * 1024 * 1024, ImagesPerRequest: 600, RequestBytes: 48 * 1024 * 1024}
	V4Pro = api.Model{Name: "deepseek-v4-pro", Context: 1_048_576, RequestBytes: 48 * 1024 * 1024}
)

The models DeepSeek serves, ready to pass as Conf.Model, with the windows its pricing page publishes (https://api-docs.deepseek.com/quick_start/pricing, read 2026-11-06). Both read 1,048,576 tokens, the exact figure the server names when a conversation does not fit. The legacy ids deepseek-v4-flash and deepseek-v4-flash-vision-exp are still served by Flash; to have turns stamped with one, pass your own api.Model.

Only Flash reads images, and its image fields follow the vision guide (https://api-docs.deepseek.com/guides/vision, read 2026-11-06): 600 images per request, each downscaled to about 1300x1300 pixels, at most 8192 pixels per side (4096 once a request carries 15 or more images), and 32 MiB per base64 or external URL image, which the guide does not say is counted before or after base64, so ImageBytes is the raw size that encodes to it.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	// Status is the HTTP status.
	Status int
	// Type is the error envelope's type, empty when the body was not JSON.
	Type string
	// Code is the envelope's code as a string, empty when absent.
	Code string
	// Message is the envelope's message, empty when the body was not JSON.
	Message string
	// Body is the response body verbatim.
	Body string
	// RetryAfter is the Retry-After header's wait, zero when absent or
	// unparseable; DeepSeek does not document sending it.
	RetryAfter time.Duration
}

APIError is a non 200 response. It arrives as the Err of an api.EventErr; read it with errors.As. Branch on the event's Code, which follows the status except that a 400, 413 or 422 reporting the context limit is api.CodeContextLength; DeepSeek does not reliably answer failures with JSON, so the other fields are best effort and meant for logs.

func (*APIError) Error

func (e *APIError) Error() string

Error returns "deepseek: http <status> (<code>): <message>", without the code when there is none, and with the body, cut to 512 characters, or the status text when there is no message.

type Conf

type Conf struct {
	// Model is the model every turn is sent to, such as Flash or V4Pro. There
	// is no default: New refuses an empty Model.Name.
	Model api.Model `json:"model"`
}

Conf holds the provider's model.

type Effort

type Effort string

Effort is DeepSeek's reasoning_effort: EffortNone turns thinking off, and the other levels turn it on at that depth. The zero value leaves the choice to the server, which thinks at high.

const (
	EffortNone Effort = "none"
	EffortLow  Effort = "low"
	EffortHigh Effort = "high"
	EffortMax  Effort = "max"
)

The reasoning_effort levels DeepSeek documents.

type FinishError

type FinishError struct {
	// Reason is the finish_reason exactly as the server sent it.
	Reason string
}

FinishError is a finish_reason that ended the turn without a reply worth keeping. It arrives as the Err of an api.EventErr: "length" as api.CodeCapped, "content_filter" as api.CodeRefused, "insufficient_system_resource" as api.CodeBusy, "aborted" as api.CodeNetwork, and any other value as api.CodeUnknown.

func (*FinishError) Error

func (e *FinishError) Error() string

Error returns "deepseek: finish_reason " followed by Reason.

type Option

type Option func(*Provider) error

Option configures a Provider at New. An option that returns an error makes New return it.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the key, overriding DEEPSEEK_API_KEY. New refuses an empty key; the server rejects a wrong one with api.CodeAccess.

func WithBaseURL

func WithBaseURL(base string) Option

WithBaseURL points the provider at another host, such as a proxy or a test server, without the /chat/completions path; a trailing slash is trimmed. An empty value or one without a scheme and host makes New fail. https://api.deepseek.com/anthropic speaks a different wire format and does not work here.

func WithEffort

func WithEffort(e Effort) Option

WithEffort sets the reasoning level. EffortNone sends thinking disabled and no reasoning_effort; the other levels send thinking enabled and that reasoning_effort; unset sends thinking enabled and leaves the level to the server. With thinking on, DeepSeek refuses a forced tool choice, so on a declared model a request whose ToolChoice is api.ToolChoiceAny or names a tool fails with a *RequestError unless the effort is EffortNone; any other model is sent the choice as it is.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient replaces the default client, for a proxy, middleware or a test server; it must not be nil. Leave its Timeout at zero: it caps the whole streamed turn. Use WithTransport to bound a dead connection.

func WithMaxTokens

func WithMaxTokens(n int) Option

WithMaxTokens caps the response; a turn that hits it ends with api.CodeCapped. At 0, the default, no cap is sent and the server's default applies. A negative value makes New fail, and so does one over the documented 393,216 ceiling on a model declared here.

func WithStop

func WithStop(stop ...string) Option

WithStop sets stop sequences, replacing any set before. DeepSeek takes up to sixteen; more are not checked here and are left to the server.

func WithTemperature

func WithTemperature(t float64) Option

WithTemperature sets temperature, from 0 to 2. DeepSeek ignores it in thinking mode, so on a declared model New refuses it without WithEffort(EffortNone).

func WithTopP

func WithTopP(t float64) Option

WithTopP sets top_p, above 0 and at most 1. Only two settings honor it: deepseek-v4-pro with WithEffort(EffortNone), and deepseek-flash (or deepseek-v4-flash or deepseek-v4-flash-vision-exp) with thinking on, where the server raises values below 0.95 to 0.95. DeepSeek fixes top_p everywhere else, so New refuses it there; on a model not declared here it is sent as configured.

func WithTransport

func WithTransport(opt lib.Options) Option

WithTransport sets the stream limits documented on lib.Options: how long the wire may stay silent and how large one event may grow. A zero field keeps lib's default. The idle deadline covers the wait for response headers and resets on every complete event and on every comment or blank line between events, including the keep-alive comments DeepSeek sends while a request is queued, so it catches a dead connection rather than a slow turn; a turn that crosses it ends with api.CodeNetwork.

func WithUserID

func WithUserID(id string) Option

WithUserID sets user_id, which partitions DeepSeek's cache and concurrency allowance by user. Requests with different ids share no cache, so leave it unset unless that isolation is wanted, and keep it fixed per provider. An id over 512 bytes, the documented limit, makes New fail.

type Provider

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

Provider is one DeepSeek configuration: a model plus the settings api.Request leaves out (effort, sampling, stop sequences, response cap). It is safe for concurrent use and holds no per turn state.

func New

func New(conf Conf, opts ...Option) (*Provider, error)

New builds a Provider for conf.Model. The key defaults to DEEPSEEK_API_KEY. New returns the first option error, and an error for an empty Model.Name or a missing key. The model rules follow the exact id: deepseek-flash and its legacy ids deepseek-v4-flash and deepseek-v4-flash-vision-exp take images and honor top_p with thinking on; deepseek-v4-pro takes no images and honors top_p with thinking off. On those models New also returns an error for an Effort outside the declared levels, WithTemperature without WithEffort(EffortNone), WithTopP where the model ignores it, and WithMaxTokens over the documented ceiling. Any other id takes no images, and New checks nothing more for it: every option is sent as configured. The default HTTP client has no timeout, because DeepSeek may queue a request for minutes before answering; WithTransport bounds a dead connection instead.

func (*Provider) Model

func (p *Provider) Model() api.Model

Model returns the model from Conf. It is fixed for the provider's lifetime.

func (*Provider) Name

func (p *Provider) Name() string

Name returns "deepseek".

func (*Provider) Stream

func (p *Provider) Stream(ctx context.Context, req api.Request) <-chan api.Event

Stream runs one turn on its own goroutine and returns its events. A turn that finishes ends in exactly one EventOk or EventErr, then the channel closes. A cancelled ctx closes it with neither, and so does a connection that stops before any finish_reason arrived; one that stops after it ends as that finish_reason does. A request this wire cannot carry, or one over Model.RequestBytes, ends at once in EventErr with api.CodeInvalid or api.CodeTooLarge. The thread calls it; hosts normally do not.

type RequestError

type RequestError struct {
	// Reason says what was refused and names the tool or message.
	Reason string
}

RequestError is a turn this adapter refused to send because DeepSeek would reject it or it cannot be encoded faithfully: a tool name that is empty, over 128 characters, has characters other than letters, digits, _ and - or is declared twice, a forced tool choice while thinking is on, an unknown message role, or a replayed tool call with no name or whose arguments were discarded with no failed result answering it. It arrives as the Err of an api.EventErr with api.CodeInvalid, before anything is sent.

func (*RequestError) Error

func (e *RequestError) Error() string

Error returns "deepseek: " followed by Reason.

type StreamError

type StreamError struct {
	// Code is the frame's error code or type, as that host spelled it.
	Code string
	// Message is the frame's message, or the raw error when none parsed.
	Message string
	// Raw is the error payload verbatim.
	Raw string
}

StreamError is a failure reported inside an already successful response. DeepSeek documents no such frame, so it comes from a gateway or proxy in front of it. It arrives as the Err of an api.EventErr whose Code is derived from Code, api.CodeUnknown for an unrecognized one.

func (*StreamError) Error

func (e *StreamError) Error() string

Error returns "deepseek: stream error (<code>): <message>", without the parenthesised code when Code is empty.

Jump to

Keyboard shortcuts

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