AI Engineering Academy · Pelajaran

Evolusi Skema dan Keserasian Ke Belakang

Pelajaran 4 daripada 413 langkah

Evolusi Skema dan Keserasian Ke Belakang ialah pelajaran AI Engineering Academy percuma di CoddyKit. Ini ialah pelajaran 4 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran AI Engineering Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus AI Engineering Academy merangkumi sejumlah 4 pelajaran.

Sebab Skema Berubah dari Semasa ke Semasa

Skema pengekstrakan tidak bersifat statik. Keperluan perniagaan berubah, jenis dokumen baharu muncul dan anda menemui medan yang sepatutnya ditangkap sejak awal. Mengubah skema dalam saluran paip langsung mewujudkan masalah keserasian ke belakang: rekod yang telah diekstrak menggunakan skema lama, manakala rekod baharu menggunakan skema baharu. Pengurusan peralihan ini dengan selamat ialah maksud evolusi skema.

Membuat Versi Skema

Berikan nombor versi kepada setiap skema dan simpan nombor itu bersama setiap rekod yang diekstrak. Apabila anda mengubah skema, naikkan nombor versinya. Ini membolehkan anda membuat pertanyaan mengikut versi skema, menjalankan pemindahan pada rekod lama dan mengekalkan logik pengesahan yang berasingan bagi setiap versi. Medan rentetan schema_version yang ringkas dalam setiap model output sudah memadai.

from pydantic import BaseModel
from typing import Literal

class InvoiceV1(BaseModel):
    schema_version: Literal['1.0'] = '1.0'
    vendor: str
    total_amount: float

class InvoiceV2(BaseModel):
    schema_version: Literal['2.0'] = '2.0'
    vendor: str
    vendor_tax_id: str | None = None  # new field
    total_amount: float
    currency: str = 'USD'  # new field with default

Perubahan Tambahan berbanding Perubahan yang Memecahkan Keserasian

Perubahan tambahan adalah selamat: menambah medan Optional atau medan dengan nilai lalai tidak memecahkan kod pengekstrakan lama atau rekod lama. Perubahan yang memecahkan keserasian berisiko: menamakan semula medan, menukar jenis daripada rentetan kepada integer atau membuang medan akan memecahkan pengguna hiliran. Sentiasa utamakan perubahan tambahan. Apabila perubahan yang memecahkan keserasian tidak dapat dielakkan, cipta versi utama skema yang baharu dan lakukan pemindahan secara terkawal.

# Safe: additive change - add optional field
class ProductV2(BaseModel):
    name: str
    price: float
    sku: str | None = None   # NEW optional field - backward safe
    category: str = 'general'  # NEW with default - backward safe

# Risky: breaking change - rename or retype
# class ProductV2(BaseModel):
#     product_name: str  # RENAMED from name - breaks consumers
#     price_cents: int   # RETYPED from float - breaks data

Menyimpan Versi Skema dalam Pangkalan Data

Sertakan versi skema dalam jadual hasil pengekstrakan supaya anda sentiasa tahu versi yang menghasilkan setiap rekod. Lajur jsonb yang menyimpan data yang diekstrak sepenuhnya, bersama lajur teks schema_version, ialah corak yang biasa digunakan. Ini membolehkan anda menulis pertanyaan yang mengambil kira versi dan memindahkan rekod lama yang dipilih semasa tempoh trafik rendah.

-- PostgreSQL table design
CREATE TABLE extractions (
    doc_id TEXT PRIMARY KEY,
    schema_version TEXT NOT NULL,
    extracted_data JSONB NOT NULL,
    extracted_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_schema_version ON extractions(schema_version);

-- Query old records needing migration
SELECT doc_id, extracted_data
FROM extractions
WHERE schema_version = '1.0'
LIMIT 1000;

Menulis Skrip Pemindahan

Tulis skrip pemindahan bagi setiap peralihan versi skema yang membaca rekod lama, menukarkannya kepada format baharu dan menulisnya semula dengan versi baharu. Jalankan pemindahan dalam kumpulan kecil dengan transaksi supaya kegagalan tidak meninggalkan pangkalan data dalam keadaan separa dipindahkan. Sentiasa kekalkan skema lama sehingga pemindahan disahkan selesai.

import asyncpg
import json

async def migrate_v1_to_v2(pool, batch_size=100):
    async with pool.acquire() as conn:
        rows = await conn.fetch(
            'SELECT doc_id, extracted_data FROM extractions WHERE schema_version=$1 LIMIT $2',
            '1.0', batch_size
        )
        for row in rows:
            old = row['extracted_data']
            new_data = {
                'schema_version': '2.0',
                'vendor': old['vendor'],
                'vendor_tax_id': None,  # unknown for old records
                'total_amount': old['total_amount'],
                'currency': 'USD'  # assume USD for old records
            }
            await conn.execute(
                'UPDATE extractions SET extracted_data=$1, schema_version=$2 WHERE doc_id=$3',
                json.dumps(new_data), '2.0', row['doc_id']
            )

Pengesahan Selari Semasa Peralihan

Semasa pemindahan skema, jalankan pengesahan selari: lakukan pengekstrakan dengan skema lama dan baharu secara serentak untuk sampel dokumen yang masuk. Bandingkan hasilnya untuk mengesahkan bahawa skema baharu menangkap semua perkara yang ditangkap oleh skema lama, serta medan baharu. Hentikan penggunaan skema lama hanya selepas pengesahan selari menunjukkan kesetaraan yang stabil pada sampel yang signifikan secara statistik.

async def parallel_validate(text: str) -> dict:
    v1_result, v2_result = await asyncio.gather(
        extract_with_schema(text, InvoiceV1),
        extract_with_schema(text, InvoiceV2)
    )
    discrepancy = (
        v1_result.vendor != v2_result.vendor or
        abs(v1_result.total_amount - v2_result.total_amount) > 0.01
    )
    if discrepancy:
        log_discrepancy(text, v1_result, v2_result)
    return {'v1': v1_result, 'v2': v2_result, 'discrepancy': discrepancy}

Bendera Ciri untuk Pelancaran Skema

Gunakan bendera ciri untuk mengawal masa saluran paip anda beralih daripada skema lama kepada skema baharu. Ini membolehkan anda melancarkan skema baharu secara beransur-ansur kepada peratusan trafik tertentu, memantau kadar ralat dan berundur serta-merta jika berlaku masalah — tanpa menggunakan semula kod. Perkhidmatan bendera ciri seperti LaunchDarkly atau satu baris ringkas dalam pangkalan data kedua-duanya boleh digunakan.

import os

def get_active_schema():
    version = os.environ.get('EXTRACTION_SCHEMA_VERSION', '1.0')
    schemas = {
        '1.0': InvoiceV1,
        '2.0': InvoiceV2,
    }
    return schemas.get(version, InvoiceV1)

async def extract_document(text: str):
    SchemaClass = get_active_schema()
    return await extract_with_schema(text, SchemaClass)

Keserasian Pengguna dengan Jenis Kesatuan

Pengguna hiliran yang membaca data yang diekstrak perlu mengendalikan berbilang versi skema dengan baik. Gunakan kesatuan terbeza dalam kod pengguna anda yang memilih logik penghuraian yang betul berdasarkan medan schema_version. Pendekatan ini lebih teguh daripada menulis rantaian if-else bersyarat dan lebih mudah diperluas apabila versi 3 tiba.

from pydantic import BaseModel
from typing import Union, Annotated
from typing import Literal

def parse_extraction(raw: dict) -> Union[InvoiceV1, InvoiceV2]:
    version = raw.get('schema_version', '1.0')
    if version == '1.0':
        return InvoiceV1(**raw)
    elif version == '2.0':
        return InvoiceV2(**raw)
    else:
        raise ValueError(f'Unknown schema version: {version}')

Menguji Perubahan Skema Sebelum Pelancaran

Sebelum melancarkan skema baharu, jalankannya pada seluruh set ujian regresi anda: koleksi dokumen perwakilan yang dipilih dengan teliti dan mempunyai output jangkaan yang diketahui. Bandingkan skor F1 bagi setiap medan antara skema lama dan baharu. Kemerosotan F1 bagi mana-mana medan bermakna penerangan skema baharu mengelirukan model — baiki penerangan medan itu sebelum pelancaran.

def eval_schema_on_test_set(test_cases: list, SchemaClass) -> dict:
    field_f1 = {}
    for case in test_cases:
        result = extract_with_schema(case['text'], SchemaClass)
        for field in case['expected']:
            expected = case['expected'][field]
            actual = getattr(result, field, None)
            # Update precision/recall counters
            update_metrics(field_f1, field, expected, actual)
    return {k: compute_f1(v) for k, v in field_f1.items()}

Mengendalikan Penyusutan Skema

Apabila versi skema tidak lagi digunakan untuk pengekstrakan baharu, anda boleh menyusutkannya. Penyusutan bermaksud: hentikan penerimaan rekod baharu dalam versi tersebut, kekalkan kebolehbacaan rekod lama dan jadualkan tarikh penamatan apabila rekod lama akan dipindahkan atau diarkibkan. Dokumentasikan penyusutan dalam log perubahan supaya semua pengguna tahu untuk menaik taraf kod penghuraian mereka.

DEPRECATED_VERSIONS = {'1.0'}
SUNSET_DATE = '2026-09-01'

def warn_if_deprecated(version: str):
    if version in DEPRECATED_VERSIONS:
        import warnings
        warnings.warn(
            f'Schema version {version} is deprecated. '
            f'It will be removed after {SUNSET_DATE}. '
            'Migrate consumers to version 2.0.',
            DeprecationWarning,
            stacklevel=2
        )

Log Perubahan dan Komunikasi

Setiap perubahan skema mesti disertai entri log perubahan yang menerangkan perkara yang berubah, sebab perubahan, arahan pemindahan dan kesan yang dijangka. Kongsikan entri log perubahan dengan semua pasukan yang menggunakan data yang diekstrak sebelum melancarkan perubahan. Banyak bencana pemindahan skema berlaku bukan kerana kegagalan teknikal, tetapi kerana pengguna tidak dimaklumkan tentang perubahan yang bakal berlaku.

# CHANGELOG.md entry format:
# ## Schema v2.0 (2026-07-01)
# ### Changes
# - ADDED: vendor_tax_id (Optional[str]) - VAT/EIN extracted from header
# - ADDED: currency (str, default='USD') - detected from symbol/code
# ### Migration
# Run: python scripts/migrate_v1_to_v2.py --batch-size=500
# ### Consumers
# - billing-service: update parse_extraction() to handle v2
# - audit-service: query now supports currency filter

Semakan Pantas

Uji pemahaman anda tentang evolusi skema dan keserasian ke belakang dalam saluran paip pengekstrakan.

Jawab dalam pelajaran interaktif

Rumusan Pelajaran

Dalam pelajaran ini, anda mempelajari bahawa pemversian skema menyimpan pengecam versi bersama setiap rekod yang diekstrak supaya anda boleh melakukan pemindahan secara terpilih, perubahan tambahan adalah selamat manakala penamaan semula atau penukaran jenis medan memerlukan pemindahan yang teliti, dan pengesahan selari membolehkan anda mengesahkan skema baharu sebelum menghentikan penggunaan skema lama. Seterusnya, kita akan mengukur kependaman LLM dengan metrik TTFT dan TPOT.

Percuma untuk bermula

Pelajari Python dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 30
Pelajaran: 120

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Evolusi Skema dan Keserasian Ke Belakang” percuma?

Ya — teks penuh “Evolusi Skema dan Keserasian Ke Belakang” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus AI Engineering Academy, tingkat taraf kepada CoddyKit PRO. Kursus AI Engineering Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Evolusi Skema dan Keserasian Ke Belakang”?

Urus perubahan skema yang memecahkan keserasian dalam saluran paip pengekstrakan yang berjalan lama dengan membuat versi skema, memindahkan pengekstrakan sejarah dan menjalankan pengesahan selari sem… Anda berlatih AI Engineering Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan AI Engineering Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran AI Engineering Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 4 daripada 4.

Berapa lamakah pelajaran “Evolusi Skema dan Keserasian Ke Belakang” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

Instructor: Pengekstrakan Bertatip dengan Pydantic
Mengendalikan Data Separa dan Hilang
Pemprosesan Kelompok dengan Asinkron dan Baris Gilir
Evolusi Skema dan Keserasian Ke Belakang

← Kembali ke AI Engineering Academy