Help us shape the future of Go! Take the 2026 Go Developer Survey

rag

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrDailyQuotaExhausted = errors.New("embedding provider daily quota exhausted (RPD)")

ErrDailyQuotaExhausted is returned when the provider reports that a per-day quota (RPD) is exhausted. Retrying before the provider's daily reset is guaranteed to fail (and can cost money on metered APIs), so callers must stop and reschedule instead of backing off.

Functions

func CreateCollectionSnapshot 

func CreateCollectionSnapshot(ctx context.Context, httpAddr, collection string) (string, error)

CreateCollectionSnapshot triggers a full snapshot of the given collection via the Qdrant HTTP API and returns the snapshot name. The addr should be "host:httpPort" (typically port 6333).

func QdrantServerVersion 

func QdrantServerVersion(ctx context.Context, httpAddr string) (string, error)

QdrantServerVersion queries the Qdrant HTTP root endpoint and returns the reported server version string (e.g. "1.17.1"). The addr should be "host:httpPort" (typically port 6333).

func WordCount 

func WordCount(s string) int

WordCount returns the approximate token count for a string.

Types

type Chunk 

type Chunk struct {
	Index    int
	Text     string
	DocID    string
	Metadata map[string]any
}

Chunk represents a segment of a document.

func ChunkText 

func ChunkText(docID, text string, cfg ChunkConfig, metadata map[string]any) []Chunk

ChunkText splits a document into overlapping chunks. Uses word-count as a token approximation (1 token ≈ 0.75 words, so we use words * 0.75).

type ChunkConfig 

type ChunkConfig struct {
	ChunkSize    int // approximate max tokens per chunk (default 512)
	ChunkOverlap int // tokens of overlap between consecutive chunks (default 64)
}

ChunkConfig controls how documents are split into chunks.

func DefaultChunkConfig 

func DefaultChunkConfig() ChunkConfig

DefaultChunkConfig returns sensible defaults.

type CollectionStats 

type CollectionStats struct {
	PointCount    uint64
	DocumentCount int
}

CollectionStats returns the number of points and unique documents in the collection, along with the on-disk storage size in bytes.

type Document 

type Document struct {
	ID       string
	Content  string
	Metadata map[string]any
}

Document is a single document to ingest.

type EmbeddingClient 

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

EmbeddingClient calls an OpenAI-compatible /v1/embeddings endpoint.

Requests are shaped by a per-provider rate-limit policy (see Limits): batches are sized to stay inside the provider's per-minute token budget, RPM/TPM buckets pace dispatch, and a shared AIMD limiter shrinks the batch budget and concurrency whenever the provider answers 429.

func NewEmbeddingClient 

func NewEmbeddingClient(endpoint, apiKeyFile, model, docPrompt, queryPrompt string) *EmbeddingClient

NewEmbeddingClient creates an embedding client that reads the API key from a file. docPrompt is prepended to document texts; queryPrompt is prepended to query texts. Leave either empty to send raw text (suitable for OpenAI-hosted models).

func NewEmbeddingClientWithKey 

func NewEmbeddingClientWithKey(endpoint, apiKey, model, docPrompt, queryPrompt string) *EmbeddingClient

NewEmbeddingClientWithKey creates an embedding client with an explicit API key. docPrompt is prepended to document texts; queryPrompt is prepended to query texts. Leave either empty to send raw text (suitable for OpenAI-hosted models).

func (*EmbeddingClient) Embed 

func (e *EmbeddingClient) Embed(ctx context.Context, texts []string, forQuery bool) ([][]float32, error)

Embed converts texts into embedding vectors. Handles batching automatically. When forQuery is true, queryPrompt is prepended to each text (used for _rag_search); when false, docPrompt is prepended (used for _rag_ingest). When the relevant prompt is empty, texts are sent as-is — this preserves backward compatibility for models that do not need a task prefix (e.g. OpenAI's text-embedding-3-*).

Batching is adaptive: a pool of workers pulls texts off a shared cursor, assembling each request under the limiter's current character budget and pacing dispatch through the provider's RPM/TPM buckets. After a 429 the budget and concurrency shrink (multiplicative decrease) and grow back toward the preset on sustained success. The returned vectors always align 1:1 with the input texts, in input order.

func (*EmbeddingClient) ProbeDimension 

func (e *EmbeddingClient) ProbeDimension(ctx context.Context) (int, error)

ProbeDimension embeds a single placeholder string and returns the output vector length. Call once on first use to discover the model's actual embedding dimension rather than requiring users to specify it manually. Uses docPrompt for consistency; the dimension is prompt-independent.

func (*EmbeddingClient) WithRateLimits added in v0.6.3 

func (e *EmbeddingClient) WithRateLimits(rpm, tpm int) *EmbeddingClient

WithRateLimits layers explicit per-minute budgets (typically sourced from ModelProvider.spec.constraints.rpm/tpm) over the endpoint-derived preset. Non-positive values leave the preset untouched. Chainable; call before the first Embed.

type IngestResult 

type IngestResult struct {
	DocumentCount int
	ChunkCount    int
}

IngestResult contains counts from an ingestion operation.

func IngestDocuments 

func IngestDocuments(
	ctx context.Context,
	docs []Document,
	qdrantAddr string,
	collection string,
	dimensions uint64,
	embedder *EmbeddingClient,
	chunkCfg ChunkConfig,
) (*IngestResult, error)

IngestDocuments chunks, embeds, and upserts documents into Qdrant. This is the shared pipeline used by both the API handler and the controller. Documents are processed one-by-one to avoid timeouts with local embedding models.

type Limits added in v0.6.3 

type Limits struct {
	// RPM is the request-per-minute budget the client stays under.
	RPM int
	// TPM is the token-per-minute budget the client stays under. Token counts
	// are estimated from character counts (≈4 chars/token) and reconciled
	// against the API's reported usage when available.
	TPM int
	// MaxBatchChars caps the total characters sent in one embedding request.
	MaxBatchChars int
	// MaxBatchChunks caps the number of texts sent in one embedding request.
	MaxBatchChunks int
	// Concurrency caps the number of embedding requests in flight.
	Concurrency int
}

Limits describes the per-provider request shaping policy applied by EmbeddingClient: how many requests may fly in parallel, the per-minute request and token budgets, and how large a single batch may be.

A zero RPM or TPM means "unlimited" (no pacing for that dimension).

func ApplyOverrides added in v0.6.3 

func ApplyOverrides(base Limits, rpm, tpm int) Limits

ApplyOverrides layers explicit operator configuration (from ModelProvider.spec.constraints rpm/tpm) over the derived preset. Values <= 0 leave the preset untouched.

func ResolveLimits added in v0.6.3 

func ResolveLimits(endpoint string) Limits

ResolveLimits returns the rate-limit policy for an embeddings endpoint, derived from the endpoint host. It deliberately errs on the side of fewer requests for remote hosts and full speed for anything local.

type Point 

type Point struct {
	ID      string
	Vector  []float32
	Payload map[string]any
}

Point represents a vector with its metadata for upsert operations.

type QdrantClient 

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

QdrantClient wraps the official Qdrant Go gRPC client for vector operations.

func NewQdrantClient 

func NewQdrantClient(addr string) (*QdrantClient, error)

NewQdrantClient connects to a Qdrant instance at the given address. The address should be in "host:port" format (gRPC port, typically 6334).

func (*QdrantClient) Close 

func (q *QdrantClient) Close() error

Close releases the underlying gRPC connection.

func (*QdrantClient) CollectionStats 

func (q *QdrantClient) CollectionStats(ctx context.Context, collection string) (*CollectionStats, error)

CollectionStats returns point count, unique document count, and storage size.

func (*QdrantClient) EnsureCollection 

func (q *QdrantClient) EnsureCollection(ctx context.Context, name string, dimensions uint64) error

EnsureCollection creates a collection if it doesn't already exist.

func (*QdrantClient) ExistingPoints added in v0.6.3 

func (q *QdrantClient) ExistingPoints(ctx context.Context, collection string, ids []string) (map[string]string, error)

ExistingPoints returns, for each of the given point IDs that already exists in the collection, the stored "content_hash" payload value (empty string for points written before content hashing was introduced). Missing points are absent from the map.

func (*QdrantClient) Search 

func (q *QdrantClient) Search(ctx context.Context, collection string, vector []float32, topK int) ([]SearchResult, error)

Search performs a nearest neighbor search and returns the top-K results.

func (*QdrantClient) Upsert 

func (q *QdrantClient) Upsert(ctx context.Context, collection string, points []Point) error

Upsert inserts or updates points in the given collection.

type SearchResult 

type SearchResult struct {
	Score   float32
	Payload map[string]any
}

SearchResult represents a single search hit with its similarity score.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.