68e889b14c39 для вырабатываючых систем — контракты і перакрантаванні

Наступныя прытамлівкі паказваюць практычны шлях адпрацоўкі “”. Акцэнт ставяцца на контракты, пераканання і мескі для коду, а не на мотывацыйныя аспекты. Калі працуеце на стадіі агляду, спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выходзіць па частым нявыпанні. Такі список дапамагае залишацца чыстасаблівым пад час пазнейшых змян у кодзе. Запісвайце час адпрацоўкі і кост токенав або запытаў праза функцыйнае рэзультат. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі шлях пераходзіць з дэмаверсіі ў спяльныя среды.

1. Эмбеддінгі ператвараюць значэння ў геаметрыю

Этап перадачы значэння за допаможчыю 1 Embedding работае наяўней, калі яго спрыяваць як вимерную паверхню. Запісаўце адны ідеальны прыклад, адну справу з бягам і прыміткі па поверненню да пачатковага стану прычаму розширэння масштаба. Зберагайце настройкі праза код аплікацыі. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функций павінны знаходзіцца ў адном месцы, куды аператары можаць адбавляць без неабяжнага чытання всіх дадзеных. Раздзеляйце правілы часткавання дадзеных і правілы ўзяць іх. Змена адных не павінна вымагаць перапісву іншых, калі зменяюцца паказнікі якосці.

# pip install openai
# export OPENAI_API_KEY=sk-...
import math

from openai import OpenAI

client = OpenAI()


def embed(texts):
    resp = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [d.embedding for d in resp.data]


def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    na = math.sqrt(sum(x * x for x in a))
    nb = math.sqrt(sum(y * y for y in b))
    return dot / (na * nb)


q, hit, miss = embed([
    "How do I get my money back?",
    "Refunds are possible within 14 days "
    "of purchase.",
    "Data is stored in Frankfurt and "
    "encrypted at rest.",
])

print(f"refund doc:  {cosine(q, hit):.3f}")
print(f"storage doc: {cosine(q, miss):.3f}")

2. Хранільнік вектараў — это спіс, які можна рангаваць

Этап зберагча вектарных дадзейнавання 2 A работае наяўнай краща, калі яго розглядаюць як мерыемую паверхню. Запісаце адна ідеальная транскрыпцыя, адзін прыклад неудачы і прыметку па абратанні змян перш чым расширваць масштабы. Дакументаваце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў ёсць частью продукту, а не наступным этапам дапрацоўкі. Фіксаваце версіі залежнасцяў і запісвайте хэш адобраза, які выканаў дэманстрацыю. Возможнасць перадарабаткі важлівейшая за традыцыйныя знання.

class VectorStore:
    def __init__(self):
        self.texts = []
        self.vectors = []

    def add(self, texts):
        self.texts.extend(texts)
        self.vectors.extend(embed(texts))

    def top_k(self, query, k=3):
        q = embed([query])[0]
        scored = [
            (cosine(q, v), t)
            for v, t in zip(
                self.vectors, self.texts
            )
        ]
        scored.sort(
            key=lambda s: s[0], reverse=True
        )
        return scored[:k]


store = VectorStore()
store.add([
    "Refunds are possible within 14 days.",
    "The Pro plan costs 12 EUR per month.",
    "Data is stored in Frankfurt.",
])

for score, text in store.top_k(
    "can I cancel and get a refund?", k=2
):
    print(f"{score:.3f}  {text}")

3. Полны процес: запрашэнне, дапаўненне, стварэнне

Этап цэлага каналу працюе наякраўей, калі яго спрыяжваць з мерым паверхневым элементам. Зберагачыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выходзіць, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны канал. Раздзеляйце правіла часткавага апрантавання і правіла выкарыстоўвання дадзеных. Змена адных не павінна вымагаць перапісву іншых, калі зменяюцыся паказнікі якосці. Этап цэлага каналу працюе наякраўей, калі яго спрыяжваць з мерым паверхневым элементам. Зберагачыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Запісвайце час выканання і кост токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавай версіі ў спяльныя сераўы.

# examples/part07_rag.py
# Mini RAG in ~90 lines: embed -> store -> top-k
# -> stitch into messages -> generate.
#
# Setup:
#   pip install openai
#   export OPENAI_API_KEY=sk-...
#
# Run:
#   python part07_rag.py

import math

from openai import OpenAI

client = OpenAI()

EMBED_MODEL = "text-embedding-3-small"
CHAT_MODEL = "gpt-4o-mini"

# A tiny corpus. In real life these are chunks
# of your docs, not whole documents.
DOCS = [
    "Support hours are 9am to 6pm CET, "
    "Monday to Friday.",
    "Refunds are possible within 14 days "
    "of purchase, no questions asked.",
    "The Pro plan costs 12 EUR per month "
    "and includes API access.",
    "The Free plan allows 3 projects and "
    "community support only.",
    "Data is stored in Frankfurt and "
    "encrypted at rest with AES-256.",
    "You can export all your data as "
    "JSON from the settings page.",
]


def embed(texts):
    resp = client.embeddings.create(
        model=EMBED_MODEL,
        input=texts,
    )
    return [d.embedding for d in resp.data]


def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    na = math.sqrt(sum(x * x for x in a))
    nb = math.sqrt(sum(y * y for y in b))
    return dot / (na * nb)


class VectorStore:
    """A list of (vector, text) pairs. That is
    all a vector store is, before you need
    scale."""

    def __init__(self):
        self.texts = []
        self.vectors = []

    def add(self, texts):
        self.texts.extend(texts)
        self.vectors.extend(embed(texts))

    def top_k(self, query, k=3):
        q = embed([query])[0]
        scored = [
            (cosine(q, v), t)
            for v, t in zip(
                self.vectors, self.texts
            )
        ]
        scored.sort(key=lambda s: s[0], reverse=True)
        return scored[:k]



def build_messages(question, hits):
    context = "\n\n".join(
        f"[{i + 1}] {text}"
        for i, (_, text) in enumerate(hits)
    )
    system = (
        "Answer using only the context below. "
        "If the answer is not in the context, "
        "say you do not know.\n\n"
        "Context:\n" + context
    )
    return [
        {"role": "system", "content": system},
        {"role": "user", "content": question},
    ]


def ask(store, question):
    hits = store.top_k(question, k=3)
    print(f"Q: {question}")
    for score, text in hits:
        print(f"  {score:.3f}  {text[:44]}...")
    messages = build_messages(question, hits)
    resp = client.chat.completions.create(
        model=CHAT_MODEL,
        messages=messages,
    )
    return resp.choices[0].message.content


if __name__ == "__main__":
    store = VectorStore()
    store.add(DOCS)

    answer = ask(
        store,
        "Where is my data stored, and can "
        "I get it out?",
    )
    print(f"A: {answer}")

Дзе ламаецца прыкладная версія

Для стадіі «Where the toy version» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя спецыялісты должны магчыма ўвайсці крок з вядомага пункта контролю, не спрабоўваючы здогадвацца пра захаваны стан.

Чэк-ліст для аперацый

Для стадіі «Чэк-ліст для аперацый» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя спецыялісты должны магчыма ўвайсці крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра захаваны стан.

Спрытваце гэты ўрадок як кантракт межа вхіднымі дадзеннямі і пасвярджанымі выходнымі рэзультатамі. Дайце назвы элементам, задаце критэрыя успеху і не прымайце часткова завершэння без паведамлення.

Калі бюджет дазволяе, дадзіце тэст на працяванне критычнага маршруту ў системе CI з викорыстанням фіксатываў, а не рэальных платных API.

Воліце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшаў, прычына павінна быць адносна конкрэтнай адпаведальнасці, а не заплутанага процесу.

Закрепіце версіі залежнасцяў і запісаце хэш адобразу, які выканаў дэмонстрацыю. Возможнасць павторнага стварэння рэзультатаў важлівей, чым традыцыйныя знаёмства.

Дакументаваць трэба як успішны, так і патроныя маршруты. Праказы, людзкі контроль і обработка некоректных паведамленняў є часткай продукту, а не елементамі пазнейшага доўнерэшання.

Перш чым запускать стак, заморозьце версіі, зафіксавце «золаты» транскрыпты для критычнага шляху і паказвце способы абяроны. У спільных средах неабходны ліміты частоты запытоў, перакананні ў належнасці тэнантам і чысткі власнік для ротацыі секрэтных даных. Валіце простую надзейнасць працы замест крэатіўных разовых дэманстрацый.

Запіс для 68e889b14c39: не кладзіце ключы прадастаўцаў у репазітарый, задаце верхнюю межу токенаў на сесію і зберагачыце транскрыпты празаўсюды з фікстурамі eval, каб пазнейшыя замены модэляў заставаліся пораўнанымі.