Алты AI-жоба: практикалық анықтамалық

Түпнұсқада әр жобаға бес қадамнан берілген. Мұнда әр қадам ашып көрсетілген: ол не үшін керек, ішінде қандай шешімдер бар, әдетте қай жерде бұзылады, жұмыс істейтінін қалай тексеруге болады және оны менің стегіме қалай көшіруге болады. Claude API туралы деректер 2026 жылғы қазанда ресми құжаттамамен салыстырылып тексерілді.

Шолу

§ 1. Hybrid Search RAG over Internal Docs

Мәні: дереккөздерге сүйене отырып, ішкі құжаттама бойынша жауап беру. Екі ретривер (мағына бойынша және кілт сөздер бойынша) бір-бірінің әлсіз жақтарын жабады, реранкер ең жақсысын таңдайды, модель тек табылған мәтін бойынша жауап береді.

Түпнұсқа стегі: Python · LangChain · Claude API · Pinecone · rank_bm25 · Cohere Rerank · FastAPI

Менің стегімде: Go · PostgreSQL + pgvector · Postgres full-text search · Claude API (Go SDK) · API арқылы реранкер

Қадамдар

1. Құжаттарды чанктерге бөлу, эмбеддингтерді есептеу, Pinecone-ға салу.

   Белгіленген таңба саны бойынша емес, құжат құрылымы бойынша (тақырыптар, абзацтар, тізімдер) бөлу. Бағдар: бір чанкке 300-800 токен, қабаттасу 10-20%. Әр чанкте: тұрақты id, doc_id, бөлім тақырыбы, url, жаңартылған күні, қолжетімділік құқықтары. Пайдалы тәсіл: эмбеддинг алдында чанктің басына құжат пен бөлімнің атауын қосып жазу. Әйтпесе «таймаутты 30 секундқа дейін көбейтіңіз» деген фрагмент контекстін жоғалтады: неның таймауты?

2. Сол корпус бойынша BM25-индекс құру.

   Векторлық индекстегідей дәл сол чанктер жиыны және сол id-лер, әйтпесе 3-қадамдағы біріктіру бұзылады. BM25 эмбеддингтер бұлыңғыр ететін нәрселерді ұстайды: қате кодтары, артикулдар, есімдер, аббревиатуралар, тикет нөмірлері. Орыс және қазақ тілдері үшін нормализация керек (кіші регистрге келтіру, стемминг немесе лемматизация), әйтпесе «келісімшарт» пен «келісімшарттың» әртүрлі токендерге айналады.

3. Екі ретриверді де іске қосып, нәтижелерді Reciprocal Rank Fusion арқылы біріктіру.

   Әр ретривер top-N қайтарады (шамамен 50). RRF скорларды емес (dense пен BM25 шкалаларын салыстыруға келмейді), позицияларды қосады: score(d) = Σ 1 / (k + rank_i(d)), әдетте k = 60. Екі тізімде де жоғары тұрған құжат ұтады. Скорларды нормализациялаудың қажеті жоқ, әдістің бар әдемілігі осында.

4. Біріктірілген тізімді Cohere Rerank арқылы қайта ранжирлеп, top-k қалдыру.

   Реранкер (cross-encoder) сұраныс пен чанкті бірге оқиды, сондықтан эмбеддингтерден дәлірек, бірақ баяуырақ әрі қымбатырақ. Оған тек RRF-тен кейінгі кандидаттарды беру (20-50 дана), модель контекстінде 5-10 қалдыру. Бұл сапаның басты тетігі: retrieval толықтыққа, реранкер дәлдікке жауап береді.

5. Inline-сілтемелері бар жауап генерациялап, әр тұжырымның дереккөзге сүйенетінін тексеру.

   Модельге тек берілген чанктер бойынша жауап беруге рұқсат етіледі, ал сүйенетін дерек болмаса, ол «құжаттамада бұл жоқ» деп адал айтуы керек. Claude API-да Citations деген нативті функция бар: чанктер citations.enabled бар құжаттар ретінде беріледі, жауап дереккөздердегі нақты орындарға сілтемесі бар блоктармен келеді. API сілтемелердің шынымен берілген құжаттарды көрсететініне кепілдік береді, ал дәйексөз ретінде келтірілген мәтін output ретінде тарификацияланбайды. RAG-чанктер үшін custom content documents қолайлы: API оларды одан әрі бөлшектемейді. Шектеу: Citations пен structured outputs бірге қолданылмайды. «Тұжырым шынымен дереккөзден туындайды» деген тексеру сенің мойныңда қалады: таңдамалы түрде LLM-төреші арқылы.

Негізгі ойлар

• Dense пен sparse әртүрлі жерде қателеседі: эмбеддингтер синонимдерді түсінеді, бірақ кодтар мен есімдерді шатастырады; BM25 керісінше. Гибрид біреуінен барын сығып алғаннан арзанырақ.
• Алдымен толықтық, содан кейін дәлдік: кең retrieval, тар rerank.
• Қолжетімділік құқықтары генерациядан кейін емес, retrieval-ға дейін сүзіледі (метадеректер бойынша сүзгі).
• Контекст аз болғаны көбіне жақсы: 6 жақсы чанк 30 орташа чанкті жеңеді.

Код

def rrf(rankings: list[list[str]], k: int = 60) -> list[tuple[str, float]]:
    scores: dict[str, float] = {}
    for ranking in rankings:
        for rank, doc_id in enumerate(ranking, start=1):
            scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
    return sorted(scores.items(), key=lambda x: x[1], reverse=True)

candidates = rrf([dense_ids, bm25_ids])[:50]   # әрі қарай реранкерге

-- chunks: id, content, embedding vector(...), tsv tsvector
-- tsv: GENERATED ALWAYS AS (to_tsvector('russian', content)) STORED + GIN-индекс
-- $1: сұраныс эмбеддингі, $2: сұраныс мәтіні
WITH semantic AS (
  SELECT id, row_number() OVER (ORDER BY embedding <=> $1) AS rnk
  FROM chunks
  ORDER BY embedding <=> $1
  LIMIT 50
),
keyword AS (
  SELECT id, row_number() OVER (ORDER BY ts_rank_cd(tsv, q) DESC) AS rnk
  FROM chunks, websearch_to_tsquery('russian', $2) AS q
  WHERE tsv @@ q
  ORDER BY ts_rank_cd(tsv, q) DESC
  LIMIT 50
)
SELECT COALESCE(s.id, k.id) AS id,
       COALESCE(1.0 / (60 + s.rnk), 0) + COALESCE(1.0 / (60 + k.rnk), 0) AS rrf_score
FROM semantic s
FULL OUTER JOIN keyword k ON s.id = k.id
ORDER BY rrf_score DESC
LIMIT 30;

Қауіпті тұстар

• Индекстердің синхрондылығы бұзылды: құжат векторлық индексте жаңарды, ал BM25-те жаңармады. Жүктеудің бір pipeline-ы және чанктер үшін бір ақиқат көзі керек.
• rank_bm25 индексті жадта ұстайды және инкременттік жаңартуларды қолдамайды: прототип үшін қалыпты, продакшн үшін жарамайды.
• Контексті жоқ чанктер: «жоғарыны қара», екіге бөлінген кесте, сипаттамасыз код.
• Ескірген құжаттар жаңаларынан ұтып кетеді. Жаңартылған күнін ескеру немесе ескіргенін белгілеу.
• Postgres-тің кірістірілген ранжирлеуі (ts_rank_cd) BM25 емес. Нағыз BM25 үшін кеңейтімдер (мысалы, ParadeDB-нің pg_search) немесе бөлек іздеу қозғалтқышы бар.
• Postgres-те қазақ тілі үшін russian сияқты конфигурация жоқ: аралас корпус үшін simple және өзіңнің нормализацияң.

Жұмыс істейтінін қалай тексеруге болады

• Дұрыс чанктері белгілі 50-100 нақты сұрақтан тұратын golden set (04 жобасы арқылы жиналады).
• Retrieval: recall@k (керек чанк top-k ішіне түсті ме), MRR, nDCG. Әр қабаттың үлесін көру үшін dense, BM25, hybrid және hybrid + rerank бөлек өлшеу.
• Генерация: faithfulness (бәрі дереккөздермен расталған ба), жауаптың релеванттылығы, жауабы корпуста жоқ сұрақтарға берілген адал «білмеймін» үлесі.

Менің стегімде

Реранкерден басқаның бәрі бір Postgres ішінде тұрады: векторлар үшін pgvector, кілт сөздер үшін tsvector + GIN, RRF бір SQL-сұраныспен. Қозғалмалы бөліктер азаяды, индекстер синхрондылығының бұзылу мәселесі жойылады: чанкті де, екі индексті де жаңарту бір транзакцияда өтеді. Anthropic өз embedding-моделін шығармайды, құжаттамасында Voyage AI-ға сілтейді (оларда реранкерлер де бар), бірақ провайдерді өз тілің мен доменің бойынша, golden set-ті жүргізіп барып таңдаған жөн. Claude үшін Go SDK Citations функциясын қолдайды.

§ 2. Text-to-SQL with Guardrails

Мәні: табиғи тілдегі сұрақ SQL-ге және нәтижеге айналады. Сұранысты модель жазады, бірақ орындауға рұқсатты тек детерминистік код пен дерекқор құқықтары береді.

Түпнұсқа стегі: Python · Claude API · SQLAlchemy · Postgres · sqlglot · Pydantic · FastAPI

Менің стегімде: Go · pg_query_go · pgx · репликадағы read-only рөл · structured outputs бар Claude API

Қадамдар

1. Модельге схеманы және пайдаланушы сұрағын беру.

   Жалаң DDL емес, мағынасы бар схема: кестелер мен бағандарға түсініктемелер, сыртқы кілттер, enum тәрізді бағандар үшін мән мысалдары (status: 'paid' | 'refunded'), бизнес-анықтамалар («түсім = paid сомасы минус refunded»), «сұрақ → эталондық SQL» түріндегі 5-10 жұп. Кестелер ондаған болса, алдымен schema linking: жеке қадаммен релевантты кестелерді таңдап, тек соларды беру.

2. Генерацияланған SQL-ді sqlglot арқылы талдап, деструктивтінің бәрін бұғаттау.

   Регулярлы өрнектермен емес, талдау ағашымен (AST) жұмыс істеу. Denylist емес, allowlist: дәл бір statement рұқсат етіледі және ол SELECT (WITH пен UNION қоса). Оған қоса ағашты аралап шығу: CTE ішінде INSERT/UPDATE/DELETE жоқ (Postgres-те data-modifying CTE болады), тек рұқсат етілген кестелер мен бағандар, қауіпті функциялар жоқ (pg_sleep, pg_read_file, dblink және сол сияқтылар), мәжбүрлі LIMIT.

3. Алдымен оқшауланған репликада read-only режимде орындау.

   Парсер қорғаныстың бірінші шебі, бірақ кепілдікті тек дерекқор береді: қажетті кестелерге SELECT құқығы бар бөлек рөл, READ ONLY транзакция, statement_timeout, primary орнына реплика. Көп арендаторлы деректер үшін Row Level Security, сұраныс бөтен жолдарды физикалық түрде көрмеуі үшін. Орындау алдында EXPLAIN: құны өте жоғары бағаланған жоспарларды кесіп тастау.

4. Сенімділік бағасын қоса беріп, ол төмен болса растау сұрау.

   Сигнал көздері: self-consistency (SQL-дің 3-5 нұсқасын генерациялап, нәтижелерін салыстыру: сәйкес келсе, сенімділік жоғарырақ), валидация қателері мен қайталама әрекеттер саны, сұрақтың өзіндегі екіұштылық («өткен ай» қай таймзона бойынша?). Шектен төмен болса, үнсіз орындамай, SQL-ді болжамдарымен көрсету немесе нақтылаушы сұрақ қою.

5. Пайдаланушы тексере алуы үшін нәтижені SQL-мен бірге қайтару.

   Жауапта деректер, SQL, қарапайым сөзбен түсіндірме және болжамдар тізімі болады («тек paid мәртебесі бар тапсырыстар ескерілді»). SQL-ді көріп отырған пайдаланушы ешбір парсер ұстай алмайтын қателерді байқайды.

Негізгі ойлар

• Defense in depth: промпт, парсер, дерекқор құқықтары, таймауттар. Әр қабатты бұзып өтуге болады, бәрін бірге бұзу дерлік мүмкін емес.
• Ең жиі кездесетін қате қауіпті емес, жай дұрыс емес болады: синтаксистік тұрғыдан дұрыс, бірақ гранулярлығы қате, JOIN-нан шыққан қайталанулары бар немесе сүзгісі басқа сұраныс. Одан guardrails емес, схема сипаттамасы мен eval-жиынтық қорғайды.
• Модельден ішінде SQL бар мәтінді емес, {sql, assumptions, needs_clarification} құрылымын қайтаруды сұрау.

Код

import sqlglot
from sqlglot import exp

ALLOWED_TABLES = {"orders", "customers", "products"}
READ_ROOTS = (exp.Select, exp.Union, exp.Intersect, exp.Except)
WRITE_NODES = (exp.Insert, exp.Update, exp.Delete, exp.Drop, exp.Create, exp.Command)

def guard(sql: str) -> exp.Expression:
    statements = sqlglot.parse(sql, read="postgres")
    if len(statements) != 1 or statements[0] is None:
        raise ValueError("дәл бір statement керек")
    tree = statements[0]
    if not isinstance(tree, READ_ROOTS):
        raise ValueError("тек SELECT рұқсат етілген")
    if next(tree.find_all(*WRITE_NODES), None) is not None:
        raise ValueError("сұраныс ішінде жазу бар")
    cte_names = {cte.alias_or_name for cte in tree.find_all(exp.CTE)}
    for table in tree.find_all(exp.Table):
        if table.name not in ALLOWED_TABLES | cte_names:
            raise ValueError(f"кесте allowlist-те жоқ: {table.name}")
    return tree

CREATE ROLE nl2sql_reader LOGIN;          -- құпиясөз secrets арқылы
GRANT USAGE ON SCHEMA analytics TO nl2sql_reader;
GRANT SELECT ON analytics.orders, analytics.customers, analytics.products TO nl2sql_reader;
ALTER ROLE nl2sql_reader SET default_transaction_read_only = on;
ALTER ROLE nl2sql_reader SET statement_timeout = '5s';

Қауіпті тұстар

• Деректер арқылы prompt injection: қайталама итерацияларда кестелердегі мәндер модель контекстіне түседі және ішінде нұсқаулар болуы мүмкін.
• Жеке деректер: PII бар бағандарды модель көретін схемадан да, allowlist-тен де алып тастау.
• Қымбат сұраныстар: WHERE жоқ декарттық көбейтінді қауіпсіз әрі валидті, бірақ репликаны құлатады. Таймаут пен EXPLAIN осыдан.
• Диалект: модель Postgres үшін MySQL синтаксисін жазады. Промптта диалектіні анық көрсету; sqlglot транспиляция жасай алады, бірақ бұл балдақ қана.

Жұмыс істейтінін қалай тексеруге болады

• «Сұрақ → эталондық SQL» жиынтығындағы execution accuracy: сұраныстар мәтінін емес, нәтижелерін салыстыру (бір жауапты әртүрлі SQL арқылы алуға болады).
• Бұғатталған сұраныстар үлесі және олардың қаншасы бекер бұғатталғаны.
• Пайдаланушы SQL-ді түзеткен немесе қайта сұраған жауаптар үлесі.

Менің стегімде

pg_query_go нағыз Postgres парсерін қолданады, сондықтан талдау ағашы сұранысты дерекқордың өзі қалай түсінетінімен сәйкес келеді: бір диалект үшін бұл sqlglot-тан сенімдірек. Pydantic-тің орнын Go-құрылымдар мен Claude API-дағы structured outputs немесе strict tool use үшін JSON Schema басады. pgx-те транзакцияны default_transaction_read_only бар рөлдің үстінен pgx.TxOptions{AccessMode: pgx.ReadOnly} арқылы ашу: екі тәуелсіз құлып.

§ 3. LoRA Fine-Tuning Pipeline

Мәні: ашық модельді өз доменіңе қарай бір GPU-да қосымша оқыту, бұл ретте әдетте параметрлердің 1%-ынан азы ғана оқытылады. Промптинг пен RAG қажетті мінез-құлықты, форматты немесе бағаны бермегенде керек.

Түпнұсқа стегі: Python · PyTorch · Hugging Face · PEFT · bitsandbytes · Weights & Biases

Менің стегімде: оқыту Python-да қалады (экожүйе сонда) · Go-сервистің артындағы vLLM арқылы сервинг

Қадамдар

1. Өз доменіңде таза instruction-датасет жинау.

   Сапа көлемнен маңыздырақ: бірнеше жүз немесе мың тексерілген мысал ондаған мың шулы мысалдан жақсы. Бірыңғай формат (мақсатты модельдің chat template-і), дедупликация, міндет түрлері бойынша теңгерім, train-мен қиылыспайтын (дерлік көшірмелерді қоса) бөлек сақталған eval-іріктеме. Жақсы дереккөз: 04 жобасындағы нақты логтар және қолмен тексеру. Күшті модельден алынған синтетикаға рұқсат, егер оны біреу тексерген болса.

2. Базалық модельді bitsandbytes арқылы 4-bit режимінде жүктеу.

   Бұл QLoRA: база салмақтары NF4 форматына квантталып, мұздатылады, есептеулер bf16-да жүреді, тек адаптерлер оқытылады. 7-8B параметрлі модель бұл режимде 24 GB жады бар бір GPU-ға сыяды. Жад жетпесе: gradient checkpointing.

3. LoRA-адаптерлерді PEFT арқылы қосып, rank пен alpha таңдау.

   LoRA бастапқы W матрицасына тимейді, оған төмен рангты түзету қосады: W' = W + (α / r) · B·A, мұндағы өлшемі d×r болатын B мен өлшемі r×k болатын A кішкентай. r (ранг) адаптердің сыйымдылығы: стиль мен формат үшін 8-16, күрделірек міндеттер үшін 32-64. alpha үлесті масштабтайды, жиі қолданылатын эвристика alpha = r немесе alpha = 2r. target_modules: зейін проекциялары (q, k, v, o), көбіне MLP-қабаттар да, бұл әдетте сапаны көтереді.

4. Loss пен метрикаларды W&B-де бақылай отырып оқыту.

   Әр N қадам сайын train loss, eval loss, learning rate және ең бастысы, eval-жиынтықтағы міндеттің өз метрикасын логтау. LoRA үшін бағдарлар: learning rate шамамен 1e-4 ... 2e-4, 1-3 эпоха. Train loss азайып жатқанда eval loss өссе: бұл шамадан тыс оқыту, ең жақсы чекпойнтты аламыз. Loss-ты тек жауап токендері бойынша есептеу, нұсқаулық токендерін маскалау.

5. Адаптерлерді базамен біріктіріп, базалық модельмен салыстыру.

   Адаптерді 4-bit емес, bf16/fp16 форматында жүктелген базамен біріктіру: квантталған модельмен біріктіру қателер береді. Үш нұсқаны салыстыру: база өз күйінде, ең жақсы промпты бар база, қосымша оқытылған модель. Оған қоса регрессияға арналған жалпы бенчмарк: тар бағыттағы қосымша оқыту жалпы қабілеттерді нашарлатуы мүмкін (catastrophic forgetting).

Негізгі ойлар

• Fine-tuning білімді емес, мінез-құлықты өзгертеді. Ескіретін фактілерді RAG-та ұстау.
• Адал салыстыру промптсыз базамен емес, тек базаның ең жақсы промпттық нұсқасымен жүргізіледі.
• Адаптер кішкентай (мегабайттар), база біреу: әртүрлі міндеттерге бірнеше адаптер ұстауға болады.

Код

import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

bnb = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL, quantization_config=bnb, device_map="auto"
)
model = prepare_model_for_kbit_training(model)

lora = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, lora)
model.print_trainable_parameters()   # күтілгендей, параметрлердің 1%-ынан азы

from peft import PeftModel

# базаны 4-bit емес, bf16 форматында жүктейміз (transformers ескі нұсқаларында параметр torch_dtype)
base = AutoModelForCausalLM.from_pretrained(BASE_MODEL, dtype=torch.bfloat16)
merged = PeftModel.from_pretrained(base, ADAPTER_DIR).merge_and_unload()
merged.save_pretrained("merged-model")

Қауіпті тұстар

• Оқыту кезіндегі және инференс кезіндегі chat template сәйкес келмейді: продакшнда модель кенеттен «ақымақтанып» қалады.
• Eval-дың train-ге ағып кетуі: әдемі метрикалар және нөл пайда.
• Базалық модельдің лицензиясы: ашық салмақтардың бәрі коммерциялық пайдалануға рұқсат бермейді.
• Кішкентай датасеттегі үлкен ранг: шамадан тыс оқыту ойлағаннан тезірек басталады.

Жұмыс істейтінін қалай тексеруге болады

• Бөлек сақталған жиынтықтағы міндет метрикасы (exact match, F1, JSON валидтілігі, рубрика бойынша LLM-төреші) ең жақсы промпты бар базанікінен жоғары.
• Жалпы бенчмарктер төмендеген жоқ.
• Инференстің латенттілігі мен құны есептелген: сападағы ұтысты хостинг бағасы жеп қоймаған.

Менің стегімде

vLLM бір базалық модельдің үстінен бірнеше LoRA-адаптерге қызмет көрсете алады (multi-LoRA) және OpenAI-мен үйлесімді HTTP API ұсынады, Go-сервис оған кәдімгі клиент арқылы жүгінеді. Бірнеше тар міндетке бір GPU-инстанс. Бұл жоба ашық модельдер туралы: Claude мінез-құлқы промпттар, мысалдар және құралдар арқылы бапталады.

§ 4. Automated Eval Dataset Generator

Мәні: продакшн-логтарды нұсқаланған тест жиынтығына айналдыру, ол модельдің, промпттың немесе пайплайнның әр жаңа нұсқасында автоматты түрде жүргізіліп, регрессияларды релизге дейін ұстайды. Онсыз қалған бес жобадағы кез келген «жақсартулар» факт емес, жай сезім.

Түпнұсқа стегі: Python · Claude API · Pandas · Pydantic · DuckDB · Streamlit

Менің стегімде: Kafka → Object Storage ішіндегі Parquet · Parquet үстінде DuckDB · CI-да Go-дағы runner · нәтижелер Postgres-те

Қадамдар

1. Продакшн-логтардан нақты промпттар мен жауаптарды шығарып алу.

   Синтетикалық тесттер сен ойлап тапқан нәрсені тексереді; логтар шын мәнінде не сұрайтынын көрсетеді. Алдымен PII деректерін тазалау. Промптпен бірге логтау: модель мен промпт нұсқасын, берілген контекстті, пайдаланушы сигналдарын (дизлайк, қайталама сұрақ, жауапты қолмен түзету), латенттілікті, токендерді. DuckDB Parquet және JSONL файлдарын дерекқорға жүктемей, тікелей оқиды.

2. Шынымен маңызды жағдайларды табу үшін кластерлеу.

   Сұраныстар эмбеддингтері → кластерлеу (k-means немесе HDBSCAN) → модель кластерлерге адамға түсінікті атаулар береді. Әрі қарай стратификацияланған іріктеме: әр ірі кластер қамтылады; сирек, бірақ қымбат жағдайлардың (ақша, заң мәселелері, деректерді жою) салмағы арттырылады; барлық белгілі сәтсіздіктер жиынтыққа міндетті түрде кіреді. Мақсат: ең жиі сұраныстарды қайталау емес, сұраныс түрлерін қамту.

3. Эталондық жауаптарды модельмен генерациялап, содан кейін қолмен тексеру.

   Модель күтілетін жауаптың жобасын жазады, адам түзетіп, растайды: жиынтықты golden set-ке айналдыратын дәл осы қолмен өту. Ашық жауаптар үшін эталон мәтін емес, рубрика: қандай фактілер міндетті түрде болуы керек, не болмауы керек, қандай формат. Streamlit мұнда белгілеу интерфейсі ретінде: сұраныс, жоба, «қабылдау / түзету / қабылдамау» батырмалары.

4. Модельдің әр жаңа нұсқасын осы жиынтықта автоматты түрде бағалау.

   Мүмкін болған жердің бәрінде детерминистік тексерулер: валидті JSON, өрістердің сәйкестігі, exact match, міндетті фактілердің болуы. Қалғаны үшін LLM-as-judge: төреші рубриканы алып, негіздемесімен баға қояды. Төрешіні калибрлейді: 50-100 мысалда оның бағаларын адамдардың бағаларымен салыстыру. Төрешілердің белгілі бұрмалаулары: ұзын жауаптарды, жұптап салыстырудағы бірінші позицияны және өз моделінің жауаптарын ұнатады. Латенттілік маңызды емес түнгі жүргізулер үшін Message Batches API жарайды: әдеттегі шақыруларға қарағанда арзанырақ.

5. Регрессияларды пайдаланушыларға жеткенге дейін ұстау.

   Тек орташа балды емес, кластерлер бойынша салыстыру: орташа есеппен +2% бір маңызды кластердегі −15%-ды жасыруы мүмкін. Шуды ескеру: бірнеше жүргізу немесе сенім интервалы, регрессия шегі шудан үлкен. CI-да гейт ретінде қосу: маңызды кластер төмендесе, промптты өзгертетін PR мерж жасалмайды.

Негізгі ойлар

• Жиынтық тірі: продакшндағы әр инцидент багтан кейінгі регрессиялық тест сияқты тестке айналады.
• Жиынтықты код сияқты нұсқалау: релиздер мұздатылған нұсқа бойынша салыстырылады.
• Жиынтық промпттарға және few-shot мысалдарға түспеуі керек, әйтпесе сапаны емес, есте сақтауды өлшейсің.

Код

from typing import Literal
from pydantic import BaseModel

class EvalCase(BaseModel):
    id: str
    cluster: str
    input: str
    expected: str | None = None
    rubric: list[str] = []      # жауапта міндетті түрде болуы керек нәрсе
    must_not: list[str] = []    # болмауы керек нәрсе
    source: Literal["prod_log", "incident", "synthetic"]
    reviewed_by: str | None = None

SELECT prompt_version,
       count(*)                                              AS requests,
       avg(CASE WHEN feedback = 'down' THEN 1 ELSE 0 END)    AS dislike_rate,
       quantile_cont(latency_ms, 0.95)                       AS p95_ms
FROM read_parquet('logs/*.parquet')
WHERE ts >= now() - INTERVAL 7 DAY
GROUP BY prompt_version
ORDER BY prompt_version;

Қауіпті тұстар

• Тек ең жиі сұраныстардан тұратын жиынтық: жоғары балл және шеткі жағдайлар туралы нөл ақпарат.
• Модельден алынған тексерілмеген эталондар: жүйе өз қателерімен салыстырылып бағаланады.
• Төреші тестіленетін модельмен бірдей модель: бағалар асыра қойылады.
• Жиынтық ескірген: өнім өзгерді, тесттер ескі мінез-құлықты тексереді.

Жұмыс істейтінін қалай тексеруге болады

• Гейт белгілі регрессияны ұстайды: промпттың жақсы нұсқасын әдейі кері қайтарып, CI қызыл болып тұрғанына көз жеткізу.
• Төрешінің адамдармен келісімі өлшенген және қолайлы.
• Жаңа инциденттер жиынтыққа «қашан болса да» емес, тұрақты түрде түседі.

Менің стегімде

Логтар онсыз да Kafka арқылы өтеді: Parquet форматында Yandex Cloud-тағы S3-үйлесімді Object Storage қоймасына sink, DuckDB httpfs кеңейтімі арқылы тікелей сол жерден оқиды. Go-дағы runner: кейстерді Claude API арқылы конкуренттілікті шектей отырып (errgroup.SetLimit) параллель жүргізу, нәтижелер мен жүргізу тарихы Postgres-те. Талдау сервис ішінде керек болса, DuckDB-нің Go-драйвері бар.

§ 5. Semantic Caching Layer

Мәні: ұқсас сұрақ бұрын қойылған болса, модельді шақырмау. LLM алдындағы қабат мағыналық жақындық бойынша сақталған жауапты қайтарады: орынсыз жауап беру тәуекелі есебінен ақша мен жүздеген миллисекундты үнемдейді.

Түпнұсқа стегі: Python · FastAPI · Redis · OpenAI embeddings · FAISS · Claude API

Менің стегімде: LLM-клиент алдындағы Go-middleware · векторлық іздеуі бар Redis немесе pgvector · эмбеддингтердің кез келген провайдері

Қадамдар

1. Модельді шақырмас бұрын әр кіріс промпттың эмбеддингін есептеу.

   Эмбеддинг алдында мәтінді нормализациялау (бос орындарды қию, регистр). Эмбеддинг әр сұраныс үшін, сәйкессіздіктерді қоса, ақша мен ондаған миллисекундты талап етеді, сондықтан қабат сәйкестіктер үлесі жеткілікті болғанда ғана өзін ақтайды. Семантикалық қабаттың алдына хэш бойынша арзан нақты кэш қою: бірдей сұраныстар эмбеддингке дейін де жетпеуі керек.

2. Кэштен семантикалық тұрғыдан ұқсас бұрынғы промптты іздеу.

   ANN-индекс арқылы (Redis-тегі HNSW немесе жадтағы FAISS) косинустық жақындық бойынша ең жақын көрші. Тек сұраныстың «кеңістігі» ішінде іздеу: кілтке модель, жүйелік промпт нұсқасы, генерация параметрлері, құралдар жиынтығы, ал жеке жауаптар үшін пайдаланушы немесе арендатор да кіреді. Әйтпесе A пайдаланушысы B пайдаланушысы үшін генерацияланған жауапты алады.

3. Жақындық шектен жоғары болса, жауапты кэштен қайтару.

   Шек жобаның басты параметрі, ол эмбеддинг моделіне байланысты. Консервативті бастау (0.95 және одан жоғары) және «бір нәрсе / әртүрлі» деп белгіленген жұптарда іріктеу. Мағынасы әртүрлі болса да, эмбеддингтер жоғары жақындық беретін қауіпті дерлік көшірмелер: болымсыздық («жазылымды қалай тоқтатуға болады» және «жазылымның тоқтатылуына қалай жол бермеуге болады»), сандар мен күндер («наурыздағы есеп» және «мамырдағы есеп»), мәндер («ЖК үшін салықтар» және «ЖШС үшін салықтар»).

4. Сәйкессіздік болса, модельді шақырып, эмбеддингті жауаппен бірге сақтау.

   Деректер түріне қарай TTL-мен сақтау: анықтамалық ақпарат бағалар мен мәртебелер туралы жауаптардан ұзағырақ тұрады. Кэштемеу: қатесі бар жауаптарды, бас тартуларды, ағымдағы уақытқа немесе диалогтың алдыңғы хабарламаларына тәуелді жауаптарды. Негізінен жеке, өз-өзіне жеткілікті сұрақтар кэштеледі, көп қадамды контекст ешқашан дерлік сәйкес келмейді.

5. Hit rate пен үнемделген ақшаны қарапайым дашбордқа шығару.

   Метрикалар: hit rate (нақты және семантикалық бөлек), hit және miss кезіндегі p50/p95 латенттілік, үнем = сәйкестіктер × шақырудың орташа құны − барлық эмбеддингтердің құны. Ең бастысы, түпнұсқада жоқ нәрсе: false hit rate. Сәйкестіктерді таңдамалы түрде тексеруге жіберу (адамға немесе LLM-төрешіге: кэштегі жауап жаңа сұраққа сай ма).

Негізгі ойлар

• Scope-сыз кэш пайдаланушылар арасында деректердің ағып кетуі деген сөз.
• False hit rate белгісіз болса, жоғары hit rate ештеңе білдірмейді.
• Кэш кілтіндегі жүйелік промпт нұсқасы промпт өзгергендегі инвалидация мәселесін шешеді; TTL ескірген деректер мәселесін шешеді.

Код

def cached_completion(req):
    scope = (req.model, req.system_prompt_version, req.tenant_id)
    norm = normalize(req.prompt)

    if hit := exact_cache.get(hash((scope, norm))):
        return hit                                    # 1. дәл сәйкестік

    vec = embed(norm)
    match = vector_index.nearest(vec, scope=scope)
    if match and match.similarity >= THRESHOLD:
        metrics.semantic_hit(match.similarity)
        return match.response                         # 2. мағыналық сәйкестік

    resp = llm.complete(req)                          # 3. сәйкессіздік
    if is_cacheable(req, resp):
        ttl = ttl_for(req)
        vector_index.add(vec, resp, scope=scope, ttl=ttl)
        exact_cache.set(hash((scope, norm)), resp, ttl=ttl)
    return resp

Қауіпті тұстар

• Процесс жадындағы FAISS репликалар арасында ортақ болмайды және қайта іске қосқанда жоғалады.
• Құжаттама өзгерді, ал кэш ескі жауаптарды бере береді: TTL немесе оқиға бойынша айқын инвалидация керек.
• Бір мезгілдегі бірдей сәйкессіздіктер: қатарынан он сұраныс, модельді он рет шақыру.
• Шек бес мысалда «көзбен мөлшерлеп» таңдалған.

Жұмыс істейтінін қалай тексеруге болады

• Сәйкестіктер іріктемесіндегі false hit rate өлшенген және қолайлы.
• Эмбеддингтер құнын шегергеннен кейін үнем оң.
• Hit кезіндегі латенттілік miss кезіндегіден айтарлықтай төмен, ал miss кезіндегі латенттілік аздап қана өсті.

Менің стегімде

Go үшін дерлік мінсіз жоба: бұл LLM-ге қатынайтын HTTP-клиенттегі middleware. Redis стекте бұрыннан бар, онда HNSW-индексі бар векторлық іздеу де бар; балама: Postgres-тегі pgvector бар кесте. Бір мезгілдегі бірдей сәйкессіздіктерді golang.org/x/sync/singleflight біріктіреді: модель бір рет шақырылады, қалғандары сол нәтижені күтеді. hit/miss/false hit метрикаларын сервистің қалған метрикалары тұрған жерге экспорттау.

§ 6. Agent Orchestration System

Мәні: айқын күйлер графы ретіндегі агент: жоспарлайды, құралдарды шақырады, нәтижені тексереді және әрі қарай не істейтінін шешеді. Жобаның мақсаты «ақылды» емес, болжамды агент: әр әрекет типтелген, әр күй сақталған, тәуекелді әрекетті адам растайды, кез келген ақауды қайта жаңғыртуға болады.

Түпнұсқа стегі: Python · LangGraph · Claude API · Redis · Postgres · FastAPI · Celery

Менің стегімде: Go · LangGraph + Celery орнына айқын state machine немесе Temporal · ыстық күй үшін Redis · тарих үшін Postgres · оқиғалар үшін Kafka

Қадамдар

1. plan, act және reflect түйіндері бар агент графын сипаттау.

   Күй типтелген объект: мақсат, жоспар, қадамдар тарихы, құралдар нәтижелері, санауыштар. plan мақсатты қадамдарға бөледі. act құралды таңдап, шақырады. reflect нәтижені мақсатпен салыстырып, шешеді: әрі қарай жалғастыру, қайта жоспарлау, аяқтау немесе адамға эскалациялау. Өтулер шартты, бірақ қатаң шектеуіштері бар: итерациялардың ең көп саны, токендер мен ақша бюджеті, бүкіл жүргізуге таймаут. Оларсыз алғашқы «тағы бір байқап көрейін» циклі-ақ бюджетті жағып жібереді.

2. Әр құралды типтелген кіріс схемасымен тіркеу.

   JSON Schema (Pydantic-тен немесе Go-құрылымдардан) және орындауға дейінгі валидация. Claude API-да strict tool use шақыру аргументтерінің схемаға сәйкес келетініне кепілдік береді. Қателерді модельге құрылымдалған түрде қайтару («date өрісі YYYY-MM-DD форматында болуы керек»), ол өзін түзете алуы үшін. Құрал сипаттамасы да промпт: қашан қолдану, қашан қолданбау, не қайтарады. Бір-бірімен қиылысатын отыз құралдан гөрі бес нақты құрал жақсы. Жанама әсерлері бар құралдарды идемпотентті ету (әр шақыруға идемпотенттілік кілті): ретрайлар сөзсіз болады.

3. Әр қадам арасында жадты Redis-те сақтау.

   Жадтың екі түрі бар. Ағымдағы жүргізудің күйі: воркер құлағаннан кейін басынан емес, сол жерден жалғастыру үшін әр қадамнан кейін checkpoint. Ұзақ мерзімді жад: сессиялар арасындағы фактілер. LangGraph-та бұл Redis немесе Postgres бэкенді бар checkpointer. TTL бар ыстық күй үшін Redis, ұзақ сақталатын тарих пен аудит үшін Postgres.

4. Тәуекелді әрекеттер үшін адам қатысатын бақылау нүктесін қосу.

   Құралдарды тәуекел бойынша бөлу: оқу (еркін), қайтымды жазу (логтау), қайтымсыз немесе сыртқы әрекет (төлем, хат жіберу, жою, деплой): кідіріс және растау. Граф тоқтайды, күй сақталады, адамға нақты сұрау жіберіледі (не, қандай параметрлермен, неге), жауаптан кейін граф сол нүктеден жалғасады. LangGraph-та бұл checkpointer-мен бірге interrupt. Celery сияқты кезек керек, өйткені жүргізу адамды сағаттап күтуі мүмкін және HTTP-сұранысты ұстап тұрмауы керек.

5. Ақауларды қайта жаңғыртып, түзету үшін әр қадамды логтау.

   Әр қадам үшін: кіріс күйі, промпт пен модель жауабы, токендер мен құн, аргументтері мен нәтижелері бар құрал шақырулары, латенттілік, reflect шешімі. Replay: күйді checkpoint-тан қалпына келтіріп, құралдардың жазылып алынған жауаптарымен қайта іске қосу, әйтпесе сыртқы әлем өзгеріп кеткен және баг қайталанбайды. Трейсинг стандарты: OpenTelemetry, бір жүргізуге бір trace, бір қадамға бір span.

Негізгі ойлар

• Құралдардың нәтижелері нұсқаулар емес, деректер: ішінде «алдыңғы нұсқауларды елеме» деген мәтін бар веб-бет немесе хат агенттің мінез-құлқын өзгертпеуі керек.
• Қателер көбейе түседі: бір қадамдағы 95% сенімділік он қадамда шамамен 60% береді. Қадамдар азырақ, араларында тексерулер.
• Мультиагенттілік үшін мультиагенттілік сапа емес, үйлестіру мен ақау нүктелерін қосады.

Код

type Step string

const (
	StepPlan    Step = "plan"
	StepAct     Step = "act"
	StepReflect Step = "reflect"
	StepApprove Step = "await_approval"
	StepDone    Step = "done"
)

type RunState struct {
	RunID     string
	Goal      string
	Plan      []string
	History   []StepRecord
	Iteration int
	SpentUSD  float64
	Next      Step
}

func (o *Orchestrator) Run(ctx context.Context, s *RunState) error {
	for s.Next != StepDone && s.Next != StepApprove {
		if s.Iteration >= o.MaxIterations || s.SpentUSD >= o.BudgetUSD {
			return ErrBudgetExceeded
		}
		var err error
		switch s.Next {
		case StepPlan:
			err = o.plan(ctx, s)
		case StepAct:
			err = o.act(ctx, s) // тәуекелді құрал s.Next = StepApprove орнатады
		case StepReflect:
			err = o.reflect(ctx, s)
		}
		if err != nil {
			return err
		}
		s.Iteration++
		if err := o.store.Checkpoint(ctx, s); err != nil { // әр қадамнан кейін
			return err
		}
	}
	return nil
}

Қауіпті тұстар

• Лимиттер болмаған кезде шексіз циклдер және шығынның күрт өсуі.
• Сипаттамалары ұқсас құралдар көп: модель таңдауда шатасады.
• Идемпотентті емес құрал және ретрай: екі рет төлем, екі хат.
• Құралдардың жазылған жауаптарынсыз replay багты қайталамайды.

Жұмыс істейтінін қалай тексеруге болады

• Күтілетін нәтижесі бар сценарийлер жиынтығындағы task success rate (бұл 04 жобасы, тек агенттер үшін).
• Бір міндетке шаққандағы қадамдардың орташа саны және құны.
• Лимитке тірелген жүргізулер үлесі.
• Адамға эскалациялар үлесі және олардың қаншасы шынымен қажет болғаны.

Менің стегімде

Temporal (оның төл Go SDK-сы бар) 3-5 қадамдарды бірден жабады: durable execution, ретрайлар, адамнан сигналды тіпті бірнеше күн күту, replay үшін оқиғалардың толық тарихы. LangGraph + Celery + Redis checkpointer шын мәнінде дәл сол нәрсені қолмен құрастырады. Kafka қадам оқиғаларын аналитика мен аудитке жеткізеді. Агент құралдары: 01 жобасындағы RAG және 02 жобасындағы Text-to-SQL.

Жобалар қалай жүйеге айналады

Оларды қандай ретпен құрған жөн:

1. 01 RAG. Негіз: онда retrieval мен дереккөзге сүйенген жауаптарды үйренесің.
2. 04 Evals. Алғашқы жұмыс істейтін пайплайннан кейін бірден, әрі қарай сезім бойынша емес, сандар бойынша жақсарту үшін.
3. 02 Text-to-SQL. Retrieval-дың екінші түрі (құрылымдалған деректер) және guardrails мәдениеті.
4. 05 Semantic cache. Инфрақұрылымдық, жылдам, ақшалай пайданы бірден көрсетеді.
5. 06 Агент. 01 мен 02-ні құрал ретінде біріктіреді және evals болмаса басқарылмайды.
6. 03 LoRA. Бөлек дағды (ML және GPU). Логтардан деректер жиналып, промптингтің жетпейтіні дәлелденгенде мағынасы бар.

Ортақ ережелер

• Модель ұсынады, код тексереді.
• Алдымен өлшеу, содан кейін оңтайландыру.
• Қайта жаңғыртуға қажеттінің бәрін логта: модель нұсқасын, промпт нұсқасын, берілген контекстті, құралдардың жауаптарын.
• Бір сұраныстың құнын алғашқы күннен бастап есепте.
• Қолжетімділік құқықтары мен scope модельден кейін емес, модельге дейін қолданылады.
• Ең қарапайым нұсқадан баста және сандар уақыты келді дегенде ғана күрделендір.

Глоссарий

Embedding

мәтіннің мағынасын бейнелейтін вектор; мағынасы жақын мәтіндер жақын векторлар береді.

Dense / sparse retrieval

эмбеддингтер бойынша іздеу / сөздердің сәйкес келуі бойынша іздеу (BM25).

BM25

кілт сөздер бойынша ранжирлеу формуласы: сөздің құжаттағы жиілігін, оның корпуста қаншалықты сирек кездесетінін және құжат ұзындығын ескереді.

RRF (Reciprocal Rank Fusion)

бірнеше ранжирленген тізімді позициялар бойынша біріктіру: Σ 1 / (k + rank).

Reranker / cross-encoder

«сұраныс + құжат» жұбын тұтасымен бағалайтын модель; эмбеддингтерден дәлірек, бірақ баяуырақ.

Recall@k

қажетті құжат алғашқы k нәтижеге түскен сұрақтардың үлесі.

MRR, nDCG

дұрыс жауаптың қай позицияда тұрғанын ескеретін ранжирлеу метрикалары.

Faithfulness (groundedness)

жауаптағы барлық тұжырымдар дереккөздермен расталған ба.

AST

сұраныстың талдау ағашы; мәтінді емес, құрылымды тексеруге мүмкіндік береді.

Schema linking

SQL генерацияланғанға дейін релевантты кестелер мен бағандарды таңдау.

Execution accuracy

генерацияланған сұраныс нәтижесінің эталондық сұраныс нәтижесімен сәйкес келуі.

LoRA

база мұздатылған күйде салмақтарға төмен рангты қосымшалар арқылы қосымша оқыту.

QLoRA

4 битке квантталған база үстіндегі LoRA.

NF4

қалыпты таралған салмақтарға арналған 4-биттік кванттау форматы.

Rank (r) және alpha

адаптердің сыйымдылығы және оның үлесінің масштабы.

Catastrophic forgetting

тар бағытта қосымша оқытудан кейін модельдің жалпы қабілеттерін жоғалтуы.

Golden set

адам тексерген, эталондары немесе рубрикалары бар кірістер жиынтығы.

LLM-as-judge

жауапты басқа модельдің рубрика бойынша бағалауы.

Cosine similarity

векторлар арасындағы бұрыштың косинусы, мағыналық жақындық өлшемі.

HNSW

ең жақын көршілерді жуықтап іздеуге арналған графтық индекс, векторлық дерекқорлардың стандарты.

Prompt caching

провайдер жағындағы промпт префиксінің кэші; модель шақырылады, бірақ қайталау арзанырақ әрі жылдамырақ.

Checkpointer

әр қадамнан кейін агент күйін сақтау механизмі.

Human-in-the-loop (HITL)

адам шешім қабылдағанға дейін жүйе жұмысындағы кідіріс.

Idempotency key

қайталама шақыру әрекетті екінші рет орындамайтын кілт.

Durable execution

workflow прогресі процестердің құлауынан аман қалатын орындау (Temporal).

Дереккөз

Түпнұсқа: алты карточкадан тұратын карусель: Hybrid Search RAG over Internal Docs, Text-to-SQL with Guardrails, LoRA Fine-Tuning Pipeline, Automated Eval Dataset Generator, Semantic Caching Layer, Agent Orchestration System. Авторы: Bashiri Smith, Baswe AI.

Түпнұсқадан алынғаны: жобалардың атаулары, стектері және әр жобаның бес қадамы (қадамдар аударылып, ашып көрсетілген).

Қосылғаны: қадамдарға түсіндірмелер, негізгі ойлар, код, қауіпті тұстар, метрикалар, «Менің стегімде» бөлімдері, жүйе схемасы, үйрену реті, глоссарий.

Әрі қарай оқу:

• Claude API: Citations
• Claude API: Prompt caching
• Claude API: Embeddings
• Claude API: Structured outputs
• Claude API: Strict tool use
• Claude API: Batch processing
• Anthropic: Building effective agents

2026 жылғы қазанда жинақталды. Кітапхана API-лары нұсқадан нұсқаға өзгеретін жерлерде код эскиз деп белгіленген.