From a744cdc335a1709f8f599a1ee51a38bcf5edafa2 Mon Sep 17 00:00:00 2001 From: Steve Dudenhoeffer Date: Sun, 28 Jun 2026 17:57:19 -0400 Subject: [PATCH] feat(imagegen): optional per-request generation settings Add Steps, CFGScale, NegativePrompt, Sampler, Seed to imagegen.Request (pointer/empty = leave the backend's per-model default), with mirror options, and forward them in the llamaswap wire payload as the stable-diffusion.cpp fields (steps/cfg_scale/negative_prompt/ sample_method/seed). Unset fields are omitted so sd-server keeps its baked defaults. Lets callers (e.g. mort drawbots) override only what they explicitly set. --- docs/adr/0016-imagegen-interface.md | 10 +++++++ imagegen/imagegen.go | 38 +++++++++++++++++++++++++ provider/llamaswap/image.go | 28 ++++++++++++++----- provider/llamaswap/llamaswap_test.go | 42 ++++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 7 deletions(-) diff --git a/docs/adr/0016-imagegen-interface.md b/docs/adr/0016-imagegen-interface.md index a96f75f..71b8335 100644 --- a/docs/adr/0016-imagegen-interface.md +++ b/docs/adr/0016-imagegen-interface.md @@ -42,3 +42,13 @@ asked for "a new ai image interface as opposed to llm". callers (additive fields/options). - No health/failover for image models yet; if needed it can be added as a separate chain type rather than retrofitting the chat chain. + +## Update — optional per-request settings + +`Request` gained additive optional overrides — `Steps *int`, `CFGScale *float64`, +`NegativePrompt string`, `Sampler string`, `Seed *int64` — with mirror options +(`WithSteps`, …). nil/"" means "leave the backend's per-model default", so the v1 +contract is unchanged for callers that don't set them. `provider/llamaswap` +forwards them to sd-server as `steps`/`cfg_scale`/`negative_prompt`/`sample_method`/ +`seed` (omitempty). This realizes the "seeds/steps … additive fields" note above; +img2img/masks/streaming remain deferred. diff --git a/imagegen/imagegen.go b/imagegen/imagegen.go index 76474ee..090f89b 100644 --- a/imagegen/imagegen.go +++ b/imagegen/imagegen.go @@ -38,6 +38,29 @@ type Request struct { // Size is the requested resolution, e.g. "512x512" or "1024x1024"; // "" = provider default. Size string + + // The fields below are optional per-request overrides. Their zero value + // (nil pointer or empty string) means "leave the backend's own default" — + // for stable-diffusion.cpp that is the per-model default baked into the + // llama-swap launch flags. A caller overrides only what it explicitly sets. + + // Steps is the number of diffusion steps; nil = backend default. + Steps *int + + // CFGScale is the classifier-free-guidance scale; nil = backend default. + // Architecture-sensitive (SDXL likes ~7, Flux wants 1), so prefer leaving + // it nil unless the caller knows the target model. + CFGScale *float64 + + // NegativePrompt steers generation away from concepts; "" = none. + NegativePrompt string + + // Sampler selects the sampling method (e.g. "euler", "euler_a"); + // "" = backend default. + Sampler string + + // Seed fixes the RNG seed for reproducible output; nil = random. + Seed *int64 } // Result is the canonical image-generation result. @@ -60,6 +83,21 @@ func WithN(n int) Option { return func(r *Request) { r.N = n } } // WithSize sets the requested resolution (e.g. "1024x1024"). func WithSize(size string) Option { return func(r *Request) { r.Size = size } } +// WithSteps overrides the number of diffusion steps. +func WithSteps(n int) Option { return func(r *Request) { r.Steps = &n } } + +// WithCFGScale overrides the classifier-free-guidance scale. +func WithCFGScale(s float64) Option { return func(r *Request) { r.CFGScale = &s } } + +// WithNegativePrompt sets a negative prompt. +func WithNegativePrompt(s string) Option { return func(r *Request) { r.NegativePrompt = s } } + +// WithSampler overrides the sampling method (e.g. "euler", "euler_a"). +func WithSampler(s string) Option { return func(r *Request) { r.Sampler = s } } + +// WithSeed fixes the RNG seed for reproducible output. +func WithSeed(seed int64) Option { return func(r *Request) { r.Seed = &seed } } + // Apply returns a copy of the request with all options applied. Providers call // this once at the top of Generate. func (r Request) Apply(opts ...Option) Request { diff --git a/provider/llamaswap/image.go b/provider/llamaswap/image.go index e331fbd..a16a87b 100644 --- a/provider/llamaswap/image.go +++ b/provider/llamaswap/image.go @@ -27,14 +27,23 @@ type imageModel struct { id string } -// imageRequest is the OpenAI /v1/images/generations request shape. We always -// request b64_json so the bytes come back inline (no second fetch). +// imageRequest is the OpenAI /v1/images/generations request shape, plus the +// stable-diffusion.cpp extras llama-swap forwards to sd-server. We always +// request b64_json so the bytes come back inline (no second fetch). The +// optional fields are pointers/omitempty so an unset value is omitted entirely +// and sd-server falls back to the model's own default (a field name a given +// sd-server build doesn't recognize is simply ignored — harmless). type imageRequest struct { - Model string `json:"model"` - Prompt string `json:"prompt"` - N int `json:"n,omitempty"` - Size string `json:"size,omitempty"` - ResponseFormat string `json:"response_format"` + Model string `json:"model"` + Prompt string `json:"prompt"` + N int `json:"n,omitempty"` + Size string `json:"size,omitempty"` + ResponseFormat string `json:"response_format"` + Steps *int `json:"steps,omitempty"` + CFGScale *float64 `json:"cfg_scale,omitempty"` + NegativePrompt string `json:"negative_prompt,omitempty"` + SampleMethod string `json:"sample_method,omitempty"` + Seed *int64 `json:"seed,omitempty"` } type imageResponse struct { @@ -61,6 +70,11 @@ func (m *imageModel) Generate(ctx context.Context, req imagegen.Request, opts .. N: req.N, Size: req.Size, ResponseFormat: "b64_json", + Steps: req.Steps, + CFGScale: req.CFGScale, + NegativePrompt: req.NegativePrompt, + SampleMethod: req.Sampler, + Seed: req.Seed, } var resp imageResponse diff --git a/provider/llamaswap/llamaswap_test.go b/provider/llamaswap/llamaswap_test.go index a210654..4cf4d60 100644 --- a/provider/llamaswap/llamaswap_test.go +++ b/provider/llamaswap/llamaswap_test.go @@ -201,6 +201,48 @@ func TestImageGenerate(t *testing.T) { } } +func TestImageGenerateSettings(t *testing.T) { + var gotBody map[string]any + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + _ = json.NewDecoder(r.Body).Decode(&gotBody) + _, _ = w.Write([]byte(`{"created":1,"data":[{"b64_json":"` + onePixelPNG + `"}]}`)) + })) + defer srv.Close() + + p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client())) + im, _ := p.ImageModel("sd") + + // Unset overrides must be omitted entirely so sd-server keeps its own + // per-model defaults. + if _, err := im.Generate(context.Background(), imagegen.Request{Prompt: "x"}); err != nil { + t.Fatalf("Generate: %v", err) + } + for _, k := range []string{"steps", "cfg_scale", "negative_prompt", "sample_method", "seed"} { + if v, ok := gotBody[k]; ok { + t.Errorf("unset request sent %q = %v, want omitted", k, v) + } + } + + // Set overrides are forwarded with the sd-server-friendly field names. + gotBody = nil + _, err := im.Generate(context.Background(), imagegen.Request{Prompt: "x"}, + imagegen.WithSteps(8), + imagegen.WithCFGScale(3.5), + imagegen.WithNegativePrompt("blurry"), + imagegen.WithSampler("euler"), + imagegen.WithSeed(42), + ) + if err != nil { + t.Fatalf("Generate: %v", err) + } + want := map[string]any{"steps": float64(8), "cfg_scale": 3.5, "negative_prompt": "blurry", "sample_method": "euler", "seed": float64(42)} + for k, w := range want { + if gotBody[k] != w { + t.Errorf("%s = %v, want %v", k, gotBody[k], w) + } + } +} + func TestImageGenerateEmptyPrompt(t *testing.T) { p := New(WithBaseURL("http://example.invalid")) im, _ := p.ImageModel("sd")