rag

Documentation

Overview

Package rag — v0.8.438 doküman soru-cevap (RAG) servisi.

Deterministik "prefetch + narrate" deseninin retrieval'lı hali: bu paket soruyu embed eder, ClickHouse'tan en yakın chunk'ları çeker ve Copilot chat'ine hazır bir bağlam bloğu üretir; 2B model yalnız anlatır (tool-loop yok). Embedding, OpenAI-uyumlu /v1/embeddings sunan herhangi bir endpoint'ten gelir (vLLM/KServe'deki bge-m3 gibi) ve TAMAMEN config-gated'dir: endpoint girilmemişse Ready()=false ve chat bugünkü gibi RAG'siz çalışır — sessiz, dürüst degrade.

Index

• Constants
• func ChunkText(text string) []string
• func ExtractPDFText(data []byte) (text string, err error)
• func LooksLikePDF(data []byte, contentType, name string) bool
• func NewHTTPClient(timeout time.Duration, insecureSkipVerify bool) *http.Client
• type CallRecord
• type Config
• type CrawlSource
• type CrawledPage
  • func Crawl(ctx context.Context, httpc *http.Client, src CrawlSource) ([]CrawledPage, error)
• type Recorder
• type Service
  • func New() *Service
  • func (s *Service) Configure(c Config)
  • func (s *Service) EffectiveTopK() int
  • func (s *Service) Embed(ctx context.Context, texts []string) ([][]float32, error)
  • func (s *Service) Enabled() bool
  • func (s *Service) LoadPersisted(ctx context.Context, store SettingsStore) error
  • func (s *Service) Ready() bool
  • func (s *Service) SavePersisted(ctx context.Context, store SettingsStore, c Config) error
  • func (s *Service) SetRecorder(r Recorder)
  • func (s *Service) Snapshot() Config
  • func (s *Service) StartConfigRefresh(ctx context.Context, store SettingsStore, interval time.Duration)
• type SettingsStore

Constants

const SurfaceEmbedding = "embedding"

SurfaceEmbedding — /ai'daki surface etiketi. Sayfa surface'leri serbest metin olarak gruplar, yani yeni etiket için frontend'de iş yok; sabit burada ki iki yazılışa bölünmesin.

Functions

func ChunkText

func ChunkText(text string) []string

ChunkText — metni retrieval parçalarına böler.

func ExtractPDFText

func ExtractPDFText(data []byte) (text string, err error)

ExtractPDFText pulls the plain text out of a text-based PDF. Pure-Go (ledongthuc/pdf, no cgo) so the single static binary + air-gapped installs keep working. Scanned / image-only PDFs have no text layer → returns "" (no OCR). ledongthuc/pdf can panic on malformed input, so extraction is recover-guarded: a bad PDF becomes an error, never a crashed ingest.

func LooksLikePDF

func LooksLikePDF(data []byte, contentType, name string) bool

LooksLikePDF reports whether the bytes / content-type / name indicate a PDF. The %PDF- magic header is authoritative; content-type + extension are hints (servers sometimes mislabel a PDF as octet-stream).

func NewHTTPClient

func NewHTTPClient(timeout time.Duration, insecureSkipVerify bool) *http.Client

NewHTTPClient — RAG dış çağrılarının (embed + crawler) ortak client fabrikası; skipVerify self-signed iç servisler için (tempo newTempoHTTPClient emsali).

Types

type CallRecord

type CallRecord struct {
	CreatedAt   time.Time
	Surface     string
	Provider    string
	Model       string
	BaseURL     string
	DurationMs  uint32
	InputTokens uint32
	Status      string
	ErrorMsg    string
	PromptChars uint32
}

CallRecord — bir embedding BATCH'inin (tek HTTP çağrısı) kaydı.

Alan kümesi copilot.CallRecord'un ANLAMLI alt kümesidir. Eksik olanların hepsi bilinçli:

• OutputTokens: embedding üretmez, hep 0 olurdu.
• UserID/UserEmail: embed hem etkileşimli soru yolunda hem de ingest/crawler arka planında koşuyor; kullanıcı kimliği yalnız birinde var. Yarısı dolu bir sütun, /ai'da "bu embed'leri kim tetikledi" sorusuna YANLIŞ cevap verirdi.
• PromptSample/ResponseSample: YOK ve olmayacak — doküman içeriği ai_calls'a KOPYALANMAZ (maskeli-kod yolunun duruşunun aynısı, v0.9.831). Vektörler de öyle: kaydın işi maliyet ve sağlık.

PromptChars batch'teki metinlerin TOPLAM uzunluğudur; çağrının gerçekte ne kadar iş yaptığını taşıyan tek dürüst ölçü (usage yollamayan uçlarda InputTokens 0 kalır).

type Config

type Config struct {
	Endpoint string `json:"endpoint"`         // ör. http://bge-m3.ai.svc:8000/v1
	Model    string `json:"model"`            // ör. BAAI/bge-m3
	APIKey   string `json:"apiKey,omitempty"` // opsiyonel — asla geri echo edilmez
	Enabled  bool   `json:"enabled"`
	TopK     int    `json:"topK,omitempty"` // 0 → 5
	// InsecureSkipVerify (v0.9.23) — operatör-raporlu prod bug'ı:
	// air-gapped kurulumda embedding endpoint'i (vLLM/KServe) ve iç
	// wiki'ler self-signed sertifikayla koşuyor; upload chunk+embed
	// adımında TLS doğrulamasına takılıyordu. Tempo/Zoom deseninin
	// aynısı; varsayılan kapalı.
	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
	// Sources (v0.8.442) — wiki/URL kaynakları; 30 dk'lık senkron
	// tick'i her kaynağı sınırlı crawl edip hash-diff'le indeksler.
	Sources []CrawlSource `json:"sources,omitempty"`
}

Config — rag_embedding system_settings blob'u (invariant #6).

type CrawlSource

type CrawlSource struct {
	URL        string `json:"url"`
	AuthHeader string `json:"authHeader,omitempty"` // "Header: value" — asla geri echo edilmez
	Username   string `json:"username,omitempty"`
	Password   string `json:"password,omitempty"`
}

CrawlSource — Settings'ten gelen tek kaynak tanımı.

Auth iki yoldan biri (ikisi de doluysa AuthHeader kazanır):

• AuthHeader: "Header: value" ham başlık (token tabanlı wiki'ler).
• Username/Password: HTTP Basic (v0.8.451 — operatörün on-prem Azure DevOps wiki'si; PAT kullanımında kullanıcı adı boş, PAT şifre alanına). Password asla geri echo edilmez.

type CrawledPage

type CrawledPage struct {
	URL   string
	Title string
	Text  string
	Hash  string // sha256(Text) hex — diff senkronun anahtarı
}

CrawledPage — bir sayfanın çıkarılmış hali.

func Crawl

func Crawl(ctx context.Context, httpc *http.Client, src CrawlSource) ([]CrawledPage, error)

Crawl — kaynak URL'den başlayıp aynı host+prefix altında BFS. ctx iptali anında durur; hata tek sayfayı atlatır, taramayı öldürmez.

type Recorder

type Recorder interface {
	RecordCall(ctx context.Context, c CallRecord)
}

Recorder — ai_calls yazıcısı. main.go'daki adaptör uygular.

type Service

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

func New

func New() *Service

func (*Service) Configure

func (s *Service) Configure(c Config)

func (*Service) EffectiveTopK

func (s *Service) EffectiveTopK() int

func (*Service) Embed

func (s *Service) Embed(ctx context.Context, texts []string) ([][]float32, error)

Embed — metinleri embedding vektörlerine çevirir (sıra korunur).

func (*Service) Enabled

func (s *Service) Enabled() bool

Enabled — RAG etkin mi (embedding endpoint'i ŞART DEĞİL). v0.9.162: ingest/crawl bununla kapılanır; endpoint yoksa doküman METİN-ONLY girer (BM25 keyword retrieval çalışır, Ready ise ayrıca embed'lenir).

func (*Service) LoadPersisted

func (s *Service) LoadPersisted(ctx context.Context, store SettingsStore) error

LoadPersisted / SavePersisted — copilot.Service'in birebir deseni.

func (*Service) Ready

func (s *Service) Ready() bool

Ready — SEMANTİK yol (embed): endpoint + model girilmiş ve etkin.

func (*Service) SavePersisted

func (s *Service) SavePersisted(ctx context.Context, store SettingsStore, c Config) error

func (*Service) SetRecorder

func (s *Service) SetRecorder(r Recorder)

SetRecorder — boot'ta bir kez (main.go). Nil-güvenli.

func (*Service) Snapshot

func (s *Service) Snapshot() Config

func (*Service) StartConfigRefresh

func (s *Service) StartConfigRefresh(ctx context.Context, store SettingsStore, interval time.Duration)

StartConfigRefresh — multi-pod senkronu (copilot deseninin aynısı).

type SettingsStore

type SettingsStore interface {
	GetSetting(ctx context.Context, key string) ([]byte, error)
	PutSetting(ctx context.Context, key string, value []byte) error
}

SettingsStore — chstore'un ihtiyaç duyulan dilimi (copilot.SettingsStore ile aynı desen; import döngüsü yok).