為 AI 治理資料

閱讀約需 116 分鐘 分鐘,12 節 中共有 10 個範例。

版次 2026.11.31 範例於 2026年11 月 19 通過測試 108 個範例中有 108 個通過 變更內容

由 AI 翻譯。經人工以英文驗證。 我們如何製作書籍

譯自英文書,版次 2026.11.31。 閱讀原文

讀完本章,你將能在與平台其他所有讀取相同的規則下,建置 AI 助理用來學習的資料。你會只納入作者同意此用途的紀錄,以假名取代其中的個人資料並衡量偵測器漏掉了什麼,移除以 MinHash 找出的重複內容,讓每筆紀錄都附帶其來源,並讓管線在每次執行時撰寫並檢查資料集卡(dataset card)。你也將能引述歐盟《AI 法案》(EU AI Act)對訓練資料的規定。

本書一路跟隨的線上學習平台,想要一個能根據學習者在評論中所寫內容來回答的課程助理。平台打算先以這些文字作為助理回答的依據,之後再以同樣的文字微調(fine-tune)助理。review_corpus 是第 4 章擷取血緣(lineage)的四條 SQL 管線之一,它把 learning.reviews 的每一列複製到 ai.review_corpus,並附上每則評論的課程與評分。第 2 章發現 ai.review_corpus 沒有擁有者,也沒有分類,而這份複本還有四個問題。它收錄每一則評論,不論作者是否同意自己的文字用於訓練 AI。它的文字含有姓名與電子郵件,這是第 3 章在評論中發現的。它的大部分評論彼此重複。而且其中沒有任何資訊說明紀錄來自何處,因此沒有人能證明某則評論獲准納入,也無法在作者改變心意時再找到它。

本章以本書共用的 AI 資料模組 lib.ai_data 重建這項工作,助理只從這份受治理的建置結果學習:pipelines/review_corpus.sql 仍維持為第 4 章中未受治理的複本,因此 CI 會持續檢查它的血緣。此模組透過第 6 章建立的強制執行層來執行管線自己的 SQL,取代文字中殘留的個人資料,移除重複內容,並寫出語料庫、其血緣與其資料集卡。它的設定位於 governance/ai_data.toml,像政策一樣接受審查;程式碼所需的法律問題答案也在其中,每個答案都是一個預留位置,由平台的法務團隊填入其答案與理由。

此部分尚未翻譯,因此以英文呈現。

Admit only reviews whose authors consented

最近一次變動於第 2026.11.27 版

On the platform, consent to one use doesn't cover another, because the question a learner answers names the use. Article 5(1)(b) of the EU's General Data Protection Regulation (GDPR) says that personal data shall be "collected for specified, explicit and legitimate purposes and not further processed in a manner that is incompatible with those purposes" (GDPR). The code reads the recorded answer to whether training an AI is covered from [legal.consent] in governance/ai_data.toml, and decides consent per record when the corpus is built, not from the account's sign-up and not once for the whole table.

crm.learners.ai_training_consent records whether a learner agreed to their text training the platform's AI. Chapter 5 made it an attribute the access policy reads, so a read of learning.reviews for the purpose ai-training keeps only the reviews whose author's answer is true, with contact details removed. lib.ai_data.read runs the SELECT of pipelines/review_corpus.sql through the enforcement layer as analyst-1, the data-science principal, stating the purpose. lib.ai_data.build refuses to run unless the layer filters on the column the consent answer names. Compare three builds: the plain pipeline, pipelines/review_corpus.sql run as written; the governed read; and a consent filter written by hand.

Copied as written, the plain pipeline would put 120 labelled emails and 798 labelled names into the corpus, from 3,000 reviews.

The governed read keeps 436 reviews, the ones whose authors said yes. Without a purpose, the same principal gets 3,000 reviews, 0 of them with their text, so a job that forgets to state its purpose gets nothing it could train on.

Notice that the filter written by hand looks like respect for consent, which is why it's the one to recognize: it leaves out the learners who said no. It keeps 2,045 reviews, and 1,609 of them, 79%, are by learners who were never asked. The README of the platform's generated data says consent is unknown for sign-ups before Jun 1, 2025, and every learner with no answer signed up from Jan 1, 2024 to May 31, 2025. An unknown answer isn't a yes. A corpus built with that filter would be mostly text that no consent covers, and nothing about it would look wrong: no error, a plausible row count, and a condition on the consent column that a reviewer would read as correct. The enforcement layer's filter tests IS TRUE, so an unknown answer counts as no, which chapter 6 built for exactly this case.

On the platform, every review was written under one set of terms, so the card states one licence, read from [legal.licence]. A corpus that mixes sources, such as reviews and forum posts, needs a licence per record too, which is one reason every record keeps its source table.

Working rule: Decide consent per record, when the corpus is built, from the answer your legal team says covers the use, and admit only records whose answer is yes: never filter out the refusals and keep the rest. Build the corpus through the enforcement layer with its purpose stated, and have the build check that the layer filters on that answer. Keep the legal team's answers, with their reasons, in a reviewed file the code reads, and carry licences per record when a source mixes them.

此部分尚未翻譯,因此以英文呈現。

Replace personal data in the text, then measure what's left

最近一次變動於第 2026.11.27 版

Consent decides whose text may enter the corpus. It doesn't make the text free of personal data: a review names its instructor, or gives its author's email for questions. Before such text trains or grounds a model, the corpus job detects the personal data in it, replaces each value, and measures what's left, because a detector's output lists what it found and never what it missed. The truth, chapter 3's labelled spans, marks every piece of personal data the generator placed in the reviews. lib.ai_data.left counts how many labelled values are still in the text after a step, matching by value, since every replacement moves the offsets after it.

The reviews arrive from the enforcement layer with its redact_contacts mask applied, which replaces emails and phone numbers with [email] and [phone] (chapter 6). Chapter 3's detector, lib.pii.platform_detector, runs Presidio's pattern recognizers with no language model, and no pattern finds a name. So lib.ai_data.detector adds a Presidio deny list of the names the platform knows: every word of every instructor's name, which Presidio escapes and matches as a whole word, ignoring case unless told otherwise (Presidio's pattern recognizer). The list comes from crm.instructors, which analyst-1 may not read. So the platform team's own job, named in [names] in governance/ai_data.toml, builds it with the platform's own access, as the enforcement layer reads crm.learners for consent, and hands the corpus job the list, never the table. The card records which job built it and how many words it holds. lib.ai_data.known_names stands for that job. Each value found becomes a keyed pseudonym, which the next section builds. Measure each step on the reviews the corpus reads, then try a longer list, with every learner's name in it too:

corpus-personal-data-left.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Counts the labelled names and emails still in the reviews after each step of the corpus job, and the false positives of the instructors' list and of a longer one. The prose's point rests on the "then the instructors' names, PERSON left" line and the false-positive lines."""from lib import ai_data, piifrom lib.catalog import open_catalogfrom lib.enforce import Enforcer# The reviews the corpus job reads: consenting authors only, with emails and phone numbers already masked.rows = ai_data.read(Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.reviews"])))texts = {row["review_id"]: row["body"] for row in rows}    # keyed by review ID, to match the labelled values row by row# What's left of the labelled personal data after each step, matched by value against the generator's truth.detectors = {"then the pattern recognizers": pii.platform_detector(), "then the instructors' names": ai_data.detector()}# the texts as the enforcement layer leaves them, before any detector runsstages = {"masked by the enforcement layer": texts}# each detector runs alone on the masked texts; pseudonymize returns the text firststages |= {name: {i: ai_data.pseudonymize(engine, text)[0] for i, text in texts.items()} for name, engine in detectors.items()}for stage, done in stages.items():    for entity, (placed, still) in ai_data.left(done).items():        print(f"{stage}, {entity} left: {still} of {placed}")# the instructors' words, from the governance team's listnames = ai_data.known_names()print("words in the list of instructors' names:", len(names))# short words are the ones ordinary text could containprint("words in the list of 3 characters or fewer:", ", ".join(word for word in names if len(word) <= 3))false_positives = sum(ai_data.unlabelled(ai_data.detector(), texts).values())assert false_positives == 0print("false positives, instructors' names:", false_positives)# Every name the platform holds, learners' too, on the same reviews: in any case, then only as written.# the union of the instructors' words and every learner's, which the table holdslonger = sorted(set(names) | set(ai_data.known_names("crm.learners")))# matched in any case, as the platform's detector matches by defaulteveryone = ai_data.detector(longer)wrong = ai_data.unlabelled(everyone, texts)print("words in the list, with learners' names:", f"{len(longer):,}")print("false positives, with learners' names:", sum(wrong.values()))print("most common false positives:", ", ".join(f"{word} ({n})" for word, n in wrong.most_common(2)))# review 24, which the longer list changesprint("a review after:", ai_data.pseudonymize(everyone, texts[24])[0])# a word matches only as written, so a lowercase word no longer matches a capitalized namecased = ai_data.detector(longer, match_case=True)cased_wrong = sum(ai_data.unlabelled(cased, texts).values())assert cased_wrong == 0print("false positives, with learners' names, matching case:", cased_wrong)# pseudonymize with the cased detector, then count what is left by valueleft = ai_data.left({i: ai_data.pseudonymize(cased, text)[0] for i, text in texts.items()})assert left["PERSON"][1] == 0print("names left, with learners' names, matching case:", f"{left['PERSON'][1]} of {left['PERSON'][0]}")
輸出python corpus-personal-data-left.py
masked by the enforcement layer, EMAIL_ADDRESS left: 0 of 19
masked by the enforcement layer, PERSON left: 120 of 120
then the pattern recognizers, EMAIL_ADDRESS left: 0 of 19
then the pattern recognizers, PERSON left: 120 of 120
then the instructors' names, EMAIL_ADDRESS left: 0 of 19
then the instructors' names, PERSON left: 0 of 120
words in the list of instructors' names: 106
words in the list of 3 characters or fewer: Ray, Roy, Ulf, Uss, de, la
false positives, instructors' names: 0
words in the list, with learners' names: 4,316
false positives, with learners' names: 147
most common false positives: best (80), date (67)
a review after: Some videos are out of <PERSON_8e2b63a6>.
false positives, with learners' names, matching case: 0
names left, with learners' names, matching case: 0 of 120

The enforcement layer's mask leaves 0 of 19 emails and 120 of 120 names, and the pattern recognizers leave 120 of 120 names, since no pattern finds a name.

Only the instructors' list removes names. With its names added, the detector leaves 0 of 120 names and makes no false positives, although its list holds short words that ordinary text could contain: Ray, Roy, Ulf, Uss, de, la.

The longer list, with every learner's name in it too, makes 147 false positives. The most common, best (80), date (67), are surnames that are also English words, and the list turns Some videos are out of date. into Some videos are out of <PERSON_8e2b63a6>. in the corpus.

Matching case avoids both. Matched only as written, the longer list makes no false positives and leaves no names, because every name in these reviews is capitalized. On real text it would miss the names typed in lowercase that chapter 3 found in tickets. The platform keeps the instructors' list, matched in any case: instructors are the people reviews talk about, and the corpus job then holds their names instead of every learner's.

The list's result holds for this data only. The labelled spans are generated, and the generated reviews name only instructors, so they can't contain the case a list of instructors misses, such as a classmate's name. For names nobody listed, the detector to try is a named-entity model. Chapter 3 compared one, OpenAI's Privacy Filter, from a recording of its detections, scored against the labelled spans with lib.pii.score. Score it the same way, on the reviews the corpus reads:

privacy-filter-on-the-corpus.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Scores OpenAI's Privacy Filter, from its recorded detections, against the labelled spans in the reviews the corpus reads. The prose's point rests on the "names the model finds, exactly" and "names the model misses" lines."""from collections import Counterfrom lib import ai_data, piifrom lib.catalog import open_catalogfrom lib.enforce import Enforcer# Privacy Filter's eight labels, mapped to the labelled spans' entity types. A label with no type matches nothing.MATCHES = {"private_person": {"PERSON"}, "private_email": {"EMAIL_ADDRESS"}, "private_phone": {"PHONE_NUMBER"},           "private_address": {"LOCATION"}, "account_number": {"CREDIT_CARD", "IBAN_CODE"},           "private_date": {"DATE_TIME"}, "private_url": set(), "secret": set()}# The reviews the corpus job reads, with the model's recorded detections and the labelled spans in them. The model read# each review as written, before the enforcement layer's mask, which changes no name.corpus = {row["review_id"] for row in ai_data.read(Enforcer(open_catalog(["crm.learners", "learning.courses",                                                                          "learning.reviews"])))}# the model's detections as recorded, not a live call to the modelmodel, manifest = pii.recorded("pii-entities")found = [span for span in model if span.source == "reviews" and span.row_id in corpus]labelled = [span for span in pii.truth() if span.source == "reviews" and span.row_id in corpus]print("model:", manifest["model"])print("reviews measured:", len(corpus))# per entity type: [labelled, found exactly, found overlapping], then per detector label: [found, exact, overlapping]scores = pii.score(found, labelled, MATCHES)# the overlap count is unused here: the prose counts exact matches onlyplaced, exact, _ = scores.recall["PERSON"]print("labelled names:", placed)print("names the model finds, exactly:", exact)# private_person is the model's label for a name, so only that label counts as a matchmissed = pii.missed([span for span in labelled if span.entity == "PERSON"], found, {"private_person"})print("names the model misses:", len(missed))often = Counter(map(pii.text_of, missed)).most_common(3)print("names it misses most often:", ", ".join(f"{name} ({n})" for name, n in often))# What the model finds where no labelled span of the type its label maps to is: text it would replace for nothing.wrong = sum(n - overlap for n, _, overlap in scores.precision.values())print("the model's detections:", len(found))print("of them, overlapping no labelled span of their type:", wrong)
輸出python privacy-filter-on-the-corpus.py
model: openai/privacy-filter
reviews measured: 436
labelled names: 120
names the model finds, exactly: 83
names the model misses: 37
names it misses most often: Marie (4), Liwia (4), Luigi (4)
the model's detections: 102
of them, overlapping no labelled span of their type: 0

On these reviews the model can't replace the list, and this data can't show what it adds, since every name in it is on the list. It finds 83 of the 120 labelled names exactly and misses 37, most often Marie (4), Liwia (4), Luigi (4), where the list misses none.

Of its 102 detections, 0 overlap no labelled span of their type. Where text names people no list holds, run both, measured this way first.

The text that comes out can still identify people. A detector misses spans, the text can identify someone without a name, and each record keeps a review ID that leads back to its author through learning.reviews. The GDPR's Recital 26 says: "Personal data which have undergone pseudonymisation, which could be attributed to a natural person by the use of additional information should be considered to be information on an identifiable natural person" (GDPR, Recital 26). So we call the corpus pseudonymized, never anonymized.

Working rule: Detect personal data in corpus text after the enforcement layer's masks, add the identifiers your platform holds about the people the text is about, and measure what's left against labelled data, by value, after every change to the detector. Prefer a short list of the names your text is about to every name you hold, since a long list matches ordinary words. Have a job that may read the names build the list, and record which list each corpus used. Measure a named-entity model the same way before you rely on it for names no list holds. Keep the list out of the corpus, and call the result pseudonymized.

以金鑰雜湊維持假名的一致性

最近一次變動於第 2026.11.27 版

偵測到的姓名可以用佔位符 <PERSON> 取代,也可以用假名取代:假名是代表某個姓名的代號,該姓名無論出現在何處,代號都相同。平台的評論只以名字稱呼講師,而且沒有兩位講師同名,因此在這裡一個代號就代表一個人。假名保留了「誰是誰」的資訊,所以兩則稱讚同一位講師的評論,仍然看得出說的是同一人。

Presidio 的匿名化工具有 hash 運算子,自 2.2.361 版起,為了安全,它預設會對每次雜湊隨機加鹽(Presidio anonymizer)。隨機的鹽使每個雜湊值無法與下一個連結,因此不適合作為假名。若要讓相同的值得到相同的雜湊,文件指出你「必須明確提供 salt 參數」,長度至少 128 位元(16 位元組)。

語料庫作業改用自己的金鑰雜湊,透過 Presidio 的 custom 運算子實作,該運算子接受一個必須回傳字串的 lambda。lib.ai_data.pseudonym 會以只有語料庫作業持有的金鑰,對實體類型與經過大小寫摺疊的值計算 SHA-256 的 HMAC,並保留八個十六進位數字。HMAC 是 RFC 2104 所描述的、為雜湊加上金鑰的建構方式,其明訂的目標之一是「對於驗證機制的強度,能依據對底層雜湊函式的合理假設,進行完善且為人所理解的密碼學分析」(RFC 2104)。Python 標準函式庫已提供它,即 hmac,因此作業沒有理由以其他方式為雜湊加上金鑰。

語料庫中有兩則評論提到同一位講師,用兩種方式取代該姓名,可以看出哪一種能讓兩者保持連結:

keyed-pseudonyms.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Replaces the same instructor's name in two reviews by Presidio's hash, by the corpus's keyed hash and by the enforcement layer's mask. The prose's point rests on the Presidio hash lines and the keyed pseudonym line."""from collections import Counterfrom presidio_anonymizer import AnonymizerEnginefrom presidio_anonymizer.entities import InvalidParamError, OperatorConfigfrom sqlglot import expfrom lib import ai_data, enforcefrom lib.catalog import open_catalogfrom lib.enforce import Enforcerfrom lib.platform import load# Two of the corpus's reviews that name the same instructor, with what the detector found in each.layer = Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.reviews"]))engine = ai_data.detector()found = [(row["body"], engine.analyze(row["body"], language="en")) for row in ai_data.read(layer)]# the first two reviews whose only detected name is Patricknamed = [(text, spans) for text, spans in found if [text[s.start:s.end] for s in spans] == ["Patrick"]][:2]print("reviews naming Patrick:", len(named))def replaced(operator: OperatorConfig) -> list[str]:    """The value that replaced the name in each of the two reviews."""    results = [AnonymizerEngine().anonymize(text, spans, {"PERSON": operator}) for text, spans in named]    return [result.text[item.start:item.end] for result in results for item in result.items]# Presidio's hash salts each value at random, so the same name gets a different hash in each reviewhashed = replaced(OperatorConfig("hash"))assert hashed[0] != hashed[1]print("Presidio's hash, the same name in two reviews gets one value:", hashed[0] == hashed[1])# and hashing the same review again gives it a different hash toorehashed = replaced(OperatorConfig("hash"))[0]assert rehashed != hashed[0]print("Presidio's hash, one review hashed twice gets one value:", rehashed == hashed[0])# a fixed salt must be at least 16 bytes; this one is 10, so Presidio refuses ittry:    replaced(OperatorConfig("hash", {"salt": "ten bytes!"}))except InvalidParamError as error:    print("a fixed salt of 10 bytes:", error)# the custom operator's lambda returns the keyed pseudonym as the replacementkeyed = replaced(OperatorConfig("custom", {"lambda": lambda value: ai_data.pseudonym("PERSON", value)}))print("keyed pseudonyms:", ", ".join(keyed))print("the name typed in lowercase:", ai_data.pseudonym("PERSON", "patrick"))# the first word of each instructor's full namefirst_names = Counter(name.split()[0] for name in load("crm.instructors").column("full_name").to_pylist())shared = sum(n for n in first_names.values() if n > 1)assert shared == 0print("instructors who share a first name with another:", shared)# What the enforcement layer's pseudonymize mask makes of the same name, run by the layer under its own key.mask = enforce.masked("pseudonymize", exp.Literal.string("Patrick"), "VARCHAR").sql(enforce.DIALECT)print("the enforcement layer's pseudonymize mask, on the same name:", layer.run(f"select {mask}").fetchall()[0][0])# functions whose name mentions HMAC: the prose says DuckDB has nonehmac = layer.connection.sql("select count(*) from duckdb_functions() where function_name ilike '%hmac%'").fetchall()[0][0]assert hmac == 0print("HMAC functions in DuckDB:", hmac)
輸出python keyed-pseudonyms.py
reviews naming Patrick: 2
Presidio's hash, the same name in two reviews gets one value: False
Presidio's hash, one review hashed twice gets one value: False
a fixed salt of 10 bytes: Salt must be at least 16 bytes (128 bits). Provided salt is 10 bytes.
keyed pseudonyms: <PERSON_d14171be>, <PERSON_d14171be>
the name typed in lowercase: <PERSON_d14171be>
instructors who share a first name with another: 0
the enforcement layer's pseudonymize mask, on the same name: 23b3d8671d01840655296f752121aecc4f7991694260e5e1431d2b57c5e3d53f
HMAC functions in DuckDB: 0

Presidio 的 hash 讓同一個姓名在兩則評論中得到不同的值,同一則評論每次雜湊也會得到不同的值。Presidio 也會拒絕過短的固定鹽,此處為 10 位元組,並如文件所述出現 Salt must be at least 16 bytes (128 bits). Provided salt is 10 bytes.。金鑰雜湊則讓兩則評論都得到 <PERSON_d14171be>, <PERSON_d14171be>,以小寫輸入的姓名也同樣得到 <PERSON_d14171be>。

執行層的 pseudonymize 遮罩由該層對同一個姓名執行,結果為 23b3d8671d01840655296f752121aecc4f7991694260e5e1431d2b57c5e3d53f。它是對該層的金鑰接上值後計算 SHA-256,一如第 6 章所寫,而不是 HMAC,因為該層的遮罩是 SQL,而 DuckDB 2.0.0 沒有 HMAC 函式。兩者是不同金鑰下的不同建構方式,所以語料庫的假名無法與該層呈現給分析師的假名相連接。

一致性有兩項代價。持有金鑰與一份姓名清單的人,就能算出每一個假名,如第 6 章對電子郵件所示,因此金鑰應存放在機密管理工具中,絕不放進語料庫、儲存庫或日誌。金鑰假名也會把佔位符原本會合併的評論區分開來:96 個相異文字,相對於 21,下一節會對此進行量測。當文字的意義取決於區分不同的人時,例如同時提到客服人員與學習者的工單,我們建議使用金鑰假名;當下游沒有任何需要時,則使用佔位符。

實用原則: 以只有作業持有的金鑰,用 HMAC 產生假名;假名不得相互連結的每個語料庫或對象,則各自使用獨立的金鑰。絕不要在未加鹽的情況下以 Presidio 的 hash 運算子產生假名,因為在其鎖定版本中,每次雜湊都是隨機的。當兩個人可能共用同一個名字時,應對人員的 ID 而非其姓名中的某個字詞做假名化;當下游不需要區分不同的人時,則使用單純的佔位符。

此部分尚未翻譯,因此以英文呈現。

Find near-duplicates with MinHash

最近一次變動於第 2026.11.31 版

Once its names are pseudonymized, the corpus's next problem is repetition: templates, copies, a review pasted twice, the same sentence from many people. Repetition is a privacy problem as well as a quality one. Kandpal, Wallace and Raffel found that "a sequence that is present 10 times in the training data is on average generated ~1000 times more often than a sequence that is present only once" (Kandpal et al., 2022).

Near-copies need a measure of similarity. Broder defined the resemblance of two documents as the Jaccard similarity of their sets of shingles, the overlapping runs of characters or words in a text. He showed that sampling the smallest shingles under a random permutation gives an unbiased estimate of that resemblance (Broder, 1997). Taking the smallest shingle under each of many permutations gives a MinHash signature, which estimates the similarity of two texts without comparing their sets (Mining of Massive Datasets, section 3.3).

lib.ai_data.deduplicate removes exact copies first, by SHA-256 of the case-folded text with runs of white space made one. It compares what's left as sets of 5-character shingles with datasketch's MinHash and MinHashLSH, which returns candidate pairs, and confirms each candidate by its exact Jaccard similarity. A confirmed pair at 0.8 or more is a near-duplicate, unless it differs only in a name, and of each group of duplicates the record with the lowest review ID stays. The duplicate step runs on the pseudonymized reviews, and each stage reports what it removed:

corpus-duplicates.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Runs the corpus's duplicate step on the pseudonymized reviews: exact copies, then near-duplicates by MinHash LSH, each confirmed exactly, and the records kept. The prose's point rests on the "of them, differing only in a name" and "near-duplicates removed" lines."""from collections import Counterfrom lib import ai_datafrom lib.catalog import open_catalogfrom lib.enforce import Enforcer# The reviews the corpus job reads, pseudonymized, then deduplicated: exact copies, then near-duplicates.# the reviews read, each text pseudonymized; the second value counts the replacementsrows, _ = ai_data.read_pseudonymized(Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.reviews"])))# groups of reviews that stand for one record, and how many each step removedgroups, removed = ai_data.duplicate_groups(rows)print("reviews read:", len(rows))# one review per distinct normalized text: the one with the lowest review IDprint("distinct texts:", len(ai_data.exact_distinct(rows)))for step, count in removed.items():    print(f"{step}:", count)print("records kept:", len(groups))print("share of the reviews read that duplicate another:", f"{1 - len(groups) / len(rows):.0%}")# identical texts only, before normalizationtext, copies = Counter(row["body"] for row in rows).most_common(1)[0]print("the most repeated text:", text)print("its copies:", copies)# A pair MinHash finds and the exact comparison confirms, and whether it differs only in a name.distinct = [row["body"] for row in ai_data.exact_distinct(rows)]# the first confirmed pair, by position among the distinct textsi, j = sorted(ai_data.near_duplicates(distinct).confirmed)[0]print("a near-duplicate pair:", distinct[i], "|", distinct[j])print("its Jaccard similarity:", f"{ai_data.jaccard(distinct[i], distinct[j]):.2f}")# equal once each pseudonym is a placeholder: the pair differs only in which names it holdsprint("it differs only in a name:", ai_data.placeholders(distinct[i]) == ai_data.placeholders(distinct[j]))# Each record kept stands for its group's reviews, under the review ID and course of the first.# a group whose reviews come from more than one courseseveral = sum(len({row["course_id"] for row in group}) > 1 for group in groups)print("records that stand for reviews of several courses:", several)
輸出python corpus-duplicates.py
reviews read: 436
distinct texts: 96
exact duplicates removed: 340
near-duplicate pairs from LSH: 381
near-duplicate pairs confirmed: 8
of them, differing only in a name: 8
near-duplicates removed: 0
records kept: 96
share of the reviews read that duplicate another: 78%
the most repeated text: Clear explanations and good exercises.
its copies: 56
a near-duplicate pair: Some videos are out of date. <PERSON_85783bac> explains things well. Happy to talk about it, write to me at [email]. | Some videos are out of date. <PERSON_967f9ae8> explains things well. Happy to talk about it, write to me at [email].
its Jaccard similarity: 0.81
it differs only in a name: True
records that stand for reviews of several courses: 23

Most of the corpus repeats itself. Of the 436 reviews read, 78% repeat another: 340 are exact copies, and only 96 texts are distinct. That's mostly the generator's doing, since it builds reviews from a handful of fixed sentences, so measure the share on your own text before training on it.

The most repeated text, "Clear explanations and good exercises.", alone appears 56 times.

MinHash then confirms 8 pairs at 0.8 or more, such as two reviews at a similarity of 0.81 that differ only in their instructor's pseudonym. Of those pairs, 8 differ only in a name, which the platform keeps apart, so near-duplicates remove 0.

Why pairs that differ only in a name stay apart comes down to what one threshold means at different lengths. Compare the corpus's reviews with the names as written, with keyed pseudonyms and with plain placeholders, then split every pair of distinct texts by whether it differs only in a name:

names-and-near-duplicates.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Counts near-duplicate pairs of the corpus's reviews with names as written, with keyed pseudonyms and with placeholders, then splits the pairs that differ only in a name by length. The prose's point rests on the pair counts and the length ranges."""from itertools import combinationsfrom lib import ai_datafrom lib.catalog import open_catalogfrom lib.enforce import Enforcer# The reviews the corpus job reads, three ways: names as written, keyed pseudonyms, and plain placeholders.layer = Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.reviews"]))keyed, _ = ai_data.read_pseudonymized(layer)# the same reviews with each pseudonym replaced by a plain placeholder, as the third wayways = {"names as written": ai_data.read(layer), "keyed pseudonyms": keyed,        "placeholders": [row | {"body": ai_data.placeholders(row["body"])} for row in keyed]}# the similarity at which a pair is a near-duplicatethreshold = ai_data.DUPLICATES["threshold"]for way, rows in ways.items():    texts = [row["body"] for row in ai_data.exact_distinct(rows)]    print(f"{way}, distinct texts:", len(texts))    print(f"{way}, pairs at {threshold} or more:", len(ai_data.near_duplicates(texts).confirmed))# Every pair of distinct pseudonymized texts, split by whether the pair differs only in a name.# distinct texts only, so each text appears once in the pairstexts = [row["body"] for row in ai_data.exact_distinct(keyed)]name_only, other = [], []for a, b in combinations(texts, 2):    # similarity comes first, so min and max over these tuples order the pairs by it    pair = (ai_data.jaccard(a, b), len(a), a, b)    (name_only if ai_data.placeholders(a) == ai_data.placeholders(b) else other).append(pair)print("pairs that differ only in a name:", len(name_only))# the lowest and highest similarity among the name-only pairsprint("their Jaccard similarity:", f"{min(name_only)[0]:.2f} to {max(name_only)[0]:.2f}")for label, lengths in [(f"below {threshold}", [n for s, n, _, _ in name_only if s < threshold]),                       (f"at {threshold} or more", [n for s, n, _, _ in name_only if s >= threshold])]:    print(f"their length in characters, {label}:", f"{min(lengths)} to {max(lengths)}")# the most similar pair among those that differ in more than a namesimilarity, _, a, b = max(other)print("the most similar pair that differs in more than a name:", f"{similarity:.2f}")print("that pair:", a, "|", b)
輸出python names-and-near-duplicates.py
names as written, distinct texts: 96
names as written, pairs at 0.8 or more: 10
keyed pseudonyms, distinct texts: 96
keyed pseudonyms, pairs at 0.8 or more: 8
placeholders, distinct texts: 21
placeholders, pairs at 0.8 or more: 0
pairs that differ only in a name: 459
their Jaccard similarity: 0.68 to 0.83
their length in characters, below 0.8: 66 to 78
their length in characters, at 0.8 or more: 116 to 119
the most similar pair that differs in more than a name: 0.66
that pair: Clear explanations and good exercises. Happy to talk about it, write to me at [email]. | Clear explanations and good exercises. <PERSON_3026fb67> explains things well. Happy to talk about it, write to me at [email].

Which pairs reach 0.8 depends on what stands in for each name. With the names as written, 10 pairs reach 0.8, and with keyed pseudonyms 8, since a pseudonym is longer than most first names and so a larger share of a short review. With plain placeholders, the 21 distinct texts hold 0.

Among the pseudonymized texts, 459 pairs differ only in which pseudonym they hold, at similarities from 0.68 to 0.83, and the threshold splits them by length alone: those below 0.8 are 66 to 78 characters long, and those at 0.8 or more are 116 to 119 characters long.

So the task, not the threshold, decides whether such reviews are duplicates: for a model that learns how learners describe courses, they are, and for one that learns what learners say about each instructor, they aren't. The platform's assistant answers about each course and its instructor, so name_only_pairs_are_duplicates = false in governance/ai_data.toml, and deduplicate never merges two texts that are the same once their pseudonyms are placeholders. The threshold decides the other pairs. The most similar of those, at 0.66, is a review with and without its sentence about the instructor: two different reviews. The platform keeps 0.8, above that pair with a margin.

Deduplicating on text folds reviews of different courses into one record, under the review ID and course of its first review, so the corpus keeps 96 records, and 23 of them stand for reviews of several courses. For training that's the point, since the model learns from the text. For grounding an answer about one course it costs recall, which the provenance section takes up.

Working rule: Deduplicate training text in two steps, exact copies by a hash of the normalized text and then near-duplicates by MinHash, each confirmed by its exact similarity, and report how much each step removed. Pseudonymize first, so that no name reaches the comparison or the sketches and the comparison can tell which pairs differ only in a name. Keep those pairs apart when the text's meaning depends on whom it names, and compare on placeholders when it doesn't. Choose the threshold by reading the pairs close above and below it in your own text.

此部分尚未翻譯,因此以英文呈現。

Tune LSH for recall, then confirm every pair

最近一次變動於第 2026.11.31 版

MinHash signatures make each comparison cheap; locality-sensitive hashing (LSH) avoids most comparisons. LSH cuts each signature into b bands of r rows, and two texts become a candidate pair when all the rows of any one band match. Leskovec, Rajaraman and Ullman derive the chance that a pair with Jaccard similarity s becomes a candidate pair (Mining of Massive Datasets, chapter 3):

P(candidate) = 1 − (1 − sʳ)ᵇ

It's an S-shaped curve: a pair well below the threshold is rarely a candidate, a pair well above it nearly always, and near the threshold it's close to a coin toss. The curve's approximate threshold is (1/b)^(1/r). datasketch's documentation warns of both kinds of error: "There will be false positives - sets that do not satisfy your threshold but returned, and false negatives - qualifying sets that are not returned" (datasketch, MinHash LSH).

With 96 distinct texts, the platform can afford to compare every pair exactly, 4,560 pairs, and that gives the exact pairs to measure LSH against. LSH sees only similarity, so it must return every pair at 0.8, whatever the name rule then decides. Score LSH against the exact comparison, tuned for 0.8 and tuned lower, each under datasketch's default hashing and under the hashing it used before its 2.0.0 release:

lsh-misses-near-duplicates.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Measures the pairs LSH misses against every pair compared exactly, under two tunings and two hashing schemes, and shows what datasketch does with sketches of two schemes. The prose's point rests on the "missed" lines."""from itertools import combinationsfrom datasketch import MinHashLSHfrom lib import ai_datafrom lib.catalog import open_catalogfrom lib.enforce import Enforcerrows, _ = ai_data.read_pseudonymized(Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.reviews"])))texts = [row["body"] for row in ai_data.exact_distinct(rows)]# the similarity at which a pair is a near-duplicatethreshold = ai_data.DUPLICATES["threshold"]# Every pair compared exactly: possible at this size, and the truth LSH is measured against.pairs = {(i, j) for i, j in combinations(range(len(texts)), 2) if ai_data.jaccard(texts[i], texts[j]) >= threshold}print("pairs compared exactly:", f"{len(texts) * (len(texts) - 1) // 2:,}")print(f"pairs at a Jaccard similarity of {threshold} or more:", len(pairs))found = {}for scheme in ["affine32", "legacy"]:    # LSH tuned for the threshold, and for the lower candidate threshold    for tuned_for in [threshold, ai_data.DUPLICATES["candidate_threshold"]]:        # the bands and rows LSH chose, its candidates, and the candidates the exact check confirms        found[scheme, tuned_for] = result = ai_data.near_duplicates(texts, threshold, tuned_for, scheme)        setting = f"{scheme}, LSH tuned for {tuned_for}"        print(f"{setting}, bands:", result.bands)        print(f"{setting}, rows per band:", result.rows)        print(f"{setting}, candidate pairs:", len(result.candidates))        print(f"{setting}, confirmed:", len(result.confirmed))        # pairs the exact comparison found that LSH never proposed as candidates        missed = len(pairs - result.candidates)        print(f"{setting}, missed:", missed)        if tuned_for != threshold:            assert missed == 0  # tuned lower, LSH finds every pair under either scheme# The chance that a pair of similarity s becomes a candidate, with b bands of r rows: 1 - (1 - s^r)^b.# the bands and rows LSH chose for the threshold, as the formula uses themb, r = found["affine32", threshold].bands, found["affine32", threshold].rowsfor s in [0.8, 0.9]:    print(f"chance of a candidate at similarity {s}, LSH tuned for {threshold}:", f"{1 - (1 - s ** r) ** b:.2f}")# the S-curve's approximate threshold, which the prose compares with the threshold asked forprint("the approximate threshold, (1/b)^(1/r):", f"{(1 / b) ** (1 / r):.2f}")# What datasketch does with a sketch made under the other scheme.# an index takes sketches of one scheme, so the legacy sketch below is refusedindex = MinHashLSH(threshold=threshold, num_perm=ai_data.DUPLICATES["num_perm"])index.insert(0, ai_data.minhash(texts[0], "affine32"))try:    index.insert(1, ai_data.minhash(texts[1], "legacy"))except ValueError as error:    print("a legacy sketch in an index of affine32 sketches:", error)
輸出python lsh-misses-near-duplicates.py
pairs compared exactly: 4,560
pairs at a Jaccard similarity of 0.8 or more: 8
affine32, LSH tuned for 0.8, bands: 9
affine32, LSH tuned for 0.8, rows per band: 13
affine32, LSH tuned for 0.8, candidate pairs: 36
affine32, LSH tuned for 0.8, confirmed: 1
affine32, LSH tuned for 0.8, missed: 7
affine32, LSH tuned for 0.6, bands: 18
affine32, LSH tuned for 0.6, rows per band: 7
affine32, LSH tuned for 0.6, candidate pairs: 381
affine32, LSH tuned for 0.6, confirmed: 8
affine32, LSH tuned for 0.6, missed: 0
legacy, LSH tuned for 0.8, bands: 9
legacy, LSH tuned for 0.8, rows per band: 13
legacy, LSH tuned for 0.8, candidate pairs: 52
legacy, LSH tuned for 0.8, confirmed: 6
legacy, LSH tuned for 0.8, missed: 2
legacy, LSH tuned for 0.6, bands: 18
legacy, LSH tuned for 0.6, rows per band: 7
legacy, LSH tuned for 0.6, candidate pairs: 406
legacy, LSH tuned for 0.6, confirmed: 8
legacy, LSH tuned for 0.6, missed: 0
chance of a candidate at similarity 0.8, LSH tuned for 0.8: 0.40
chance of a candidate at similarity 0.9, LSH tuned for 0.8: 0.93
the approximate threshold, (1/b)^(1/r): 0.84
a legacy sketch in an index of affine32 sketches: MinHash scheme 'legacy' does not match scheme 'affine32' of the MinHash previously given to this index

Tuned for 0.8, datasketch's default LSH returns 36 candidate pairs, misses 7 of the 8 pairs that reach 0.8, and so confirms only 1 of them.

The formula says why. With the 9 bands of 13 rows datasketch chose, a pair at similarity 0.8 becomes a candidate with a probability of 0.40, one at 0.9 with 0.93, and the approximate threshold is 0.84, above the threshold asked for.

Under the default scheme, tuned for 0.6, LSH finds every pair and returns 381 candidates. Each candidate costs one exact comparison, against 4,560 for comparing every pair, and the exact comparison discards every pair below 0.8. So the platform tunes LSH for 0.6 and confirms at 0.8, both settings in governance/ai_data.toml.

datasketch's 2.0.0 release made affine32 the default permutation scheme of MinHash, and its release notes say that hash values differ from earlier versions, so they advise rebuilding persisted sketches and LSH indexes, or passing MinHash(..., scheme="legacy"). With the legacy scheme, LSH tuned for 0.8 returns 52 candidates and confirms 6, so a count recorded under one scheme isn't reproduced under the other.

Tuned for 0.6, both schemes find all 8 pairs. With high recall and an exact check, the result depends on the similarity, not on the hash functions.

datasketch refuses to mix schemes in one index, with MinHash scheme 'legacy' does not match scheme 'affine32' of the MinHash previously given to this index, but it won't stop you comparing old counts with new ones. The book's examples pin datasketch at 2.0.0 and write scheme = "affine32" into the settings, so an upgrade can't change a recorded count without a reviewed change.

Working rule: Tune LSH below your similarity threshold, so that it misses few pairs, and confirm every candidate by its exact similarity. Measure LSH's misses against an exhaustive comparison on a sample of your corpus whenever its settings, its library or the text change. Pin the MinHash library, write its hashing scheme into your settings, and never compare counts or stored sketches made under different schemes.

讓每一筆記錄都帶有來源資訊

最近一次變動於第 2026.11.27 版

無法追溯到來源的記錄,就無法被檢查、更正或移除。記錄層級的來源資訊(provenance)回答三個問題:它來自哪一張資料表、哪一列,以及是哪一個作業的哪一次執行把它放進語料庫。第 4 章提供了平台所需的最後一部分:作業的每一次執行都會送出 OpenLineage 事件,其執行 ID 由該次執行的時間與作業名稱推導而來,欄位層級的血緣則從作業的 SQL 解析而得。

lib.ai_data.build 在寫入每一筆記錄時,會把來源資訊放在評論本身的欄位旁邊:source_table、review_id、job 與 run_id。它以 lib.lineage.record 送出作業的執行事件。其中有一項選擇很重要:血緣是從強制執行層實際執行的查詢解析而來,其中包含同意條件過濾與遮罩,而不是從 pipelines/review_corpus.sql 中的 SQL 解析。請建立語料庫,然後把一筆記錄一路追溯回它的執行:

corpus-provenance.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Builds the corpus and follows one record back to its source row, its job and the run that wrote it, then checks that run's lineage against the query as written. The prose's point rests on the "rows filtered by" and "body" lines."""from lib import ai_data, lineage, pipelinesfrom lib.catalog import open_catalogcatalog = open_catalog(["crm.learners", "learning.courses", "learning.reviews"])built = ai_data.build(catalog)# the second record, whose text holds a pseudonymrecord = built.records.to_pylist()[1]print("a record's text:", record["body"])for column in ["source_table", "review_id", "job"]:    print(f"its {column}:", record[column])# The run that wrote it, from the lineage events: the query as the enforcement layer ran it.# the job's COMPLETE event, which carries the run's lineagecomplete = [e for e in lineage.read_events(built.folder / "events.jsonl") if e["eventType"] == "COMPLETE"][0]same_run = record["run_id"] == complete["run"]["runId"]assert same_runprint("its run_id is the COMPLETE event's run:", same_run)print("the run's inputs:", ", ".join(dataset["name"] for dataset in complete["inputs"]))# column lineage: the inputs that filter the rows, and how each field is transformedfacet = complete["outputs"][0]["facets"]["columnLineage"]# a FILTER transformation marks an input whose values decide which rows the output holdsfilters = [f"{i['name']}.{i['field']}" for i in facet["dataset"] if any(t["subtype"] == "FILTER" for t in i["transformations"])]print("rows filtered by, as run:", ", ".join(filters))# the lineage of the review text, from the reviews tabletext = [i for i in facet["fields"]["body"]["inputFields"] if (i["name"], i["field"]) == ("learning.reviews", "body")]# IDENTITY means copied unchanged; TRANSFORMATION means the value was changed on its wayprint("body, as run:", text[0]["transformations"][0]["subtype"])# the same lineage parsed from the SQL as written, with no enforcement rewritefields, rows = lineage.column_lineage(pipelines.sql(ai_data.BUILD["job"]), lineage.schema(catalog))print("rows filtered by, as written:", ", ".join(i.source for i in rows if i.subtype == "FILTER") or "nothing")print("body, as written:", fields["body"][0].subtype)# Back from every record to its review's author, with the platform's own access, against today's answers.# each record's review ID, checked against the author's consent today, not at build timeids = built.records.column("review_id").to_pylist()print("records whose author consented:", f"{ai_data.consenting(catalog, ids)} of {len(ids)}")
輸出python corpus-provenance.py
a record's text: Too fast in the second half. <PERSON_85783bac> explains things well.
its source_table: learning.reviews
its review_id: 18
its job: platform/review_corpus
its run_id is the COMPLETE event's run: True
the run's inputs: crm.learners, learning.courses, learning.reviews
rows filtered by, as run: crm.learners.ai_training_consent, learning.reviews.learner_id
body, as run: TRANSFORMATION
rows filtered by, as written: nothing
body, as written: IDENTITY
records whose author consented: 96 of 96

追溯一筆記錄,可以看出血緣必須記錄哪些內容。記錄「Too fast in the second half. <PERSON_85783bac> explains things well.」來自 learning.reviews,是評論 18,由作業 platform/review_corpus 寫入,而它的 run_id 就是該作業 COMPLETE 事件所對應的那次執行。

該次執行讀取了 crm.learners, learning.courses, learning.reviews,其血緣顯示,資料列是由 crm.learners.ai_training_consent, learning.reviews.learner_id 過濾的,這屬於決定哪些資料列存在的 INDIRECT 輸入,並且 body 是評論文字的 TRANSFORMATION。

若依管線中原本撰寫的 SQL 來解析,同一個作業的資料列則是由 nothing 過濾,而 body 是 IDENTITY 的副本。這會表示個人文字被原封不動地複製,且完全沒有牽涉同意欄位。實際執行的查詢才是真正發生的事,因此血緣記錄的是它。

來源資訊讓語料庫在事後也能被檢查。把每一筆記錄透過 learning.reviews 連回其作者,可以找出 96 of 96 筆作者曾表示同意的記錄,平台可以拿今天的答案,對任何舊的建置執行這項檢查。

來源資訊也讓檢索能夠尊重每位讀者的權限。OWASP 要求以語言模型建構的應用程式「Implement fine-grained access controls and permission-aware vector and embedding stores」(OWASP LLM08:2025)。平台以這個語料庫建立的索引來回答某位使用者,該索引把每筆記錄的 review_id 與其向量一併保存。在檢索到的記錄送達模型之前,檢索層會以被回答者的身分向強制執行層詢問,這些評論中有哪些是他們可以閱讀的,做法就像第 6 章執行助理的查詢那樣,並捨棄其餘的記錄。於是講師只會得到來自自己課程的記錄。一筆代表多門課程評論的記錄,只帶有第一則評論的 ID,因此這項檢查會採取失敗即封閉的做法:對於 23 筆這類記錄中的每一筆,它可能隱藏某段使用者原本可以閱讀的文字,但絕不會顯示使用者不能閱讀的文字。

實用原則: 為每一筆記錄附上其來源資料表、該列的 ID,以及寫入它的作業與執行,並依查詢實際執行的樣子(包含過濾條件與遮罩)記錄作業的血緣。透過這些來源資訊,以今天的同意狀態檢查舊的建置。在模型看到任何記錄之前,依讀者本人對每筆記錄來源資料列的權限決定,過濾每一次檢索。

此部分尚未翻譯,因此以英文呈現。

Generate the dataset card from the run

最近一次變動於第 2026.11.27 版

A dataset card tells whoever trains or audits a model what's in its data, where it came from and what was done to it. Croissant is MLCommons' metadata format for machine-learning datasets (Akhtar et al., 2024). Its 1.1 specification makes a card checkable: "Croissant datasets must declare that they conform to the versioned schema, e.g. http://mlcommons.org/croissant/1.1", and every dataset must give a description, licence, name, URL, creator and publication date. For provenance, the specification recommends the W3C PROV Ontology (PROV-O) (Croissant 1.1). Its responsible-AI vocabulary adds properties such as rai:dataCollection and rai:personalSensitiveInformation (Croissant RAI 1.0). A card written by hand describes the data someone meant to build; a card generated by the run describes the data it built.

lib.ai_data.card generates the platform's card with mlcroissant 1.1.1, MLCommons' Python library for Croissant. The run supplies the counts, the corpus file's SHA-256, a field for every column, and three PROV-O properties: the tables the pipeline's own SQL reads, which the values come from, as prov:wasDerivedFrom; the table the enforcement layer's rewrite adds, which only decides which rows exist, as prov:wasInfluencedBy; and the run, as prov:wasGeneratedBy. mlcroissant writes them through its extra_properties argument but adds no prov prefix to the card's context, so the module adds it. The creator is the owner of ai.review_corpus in governance/metadata.toml. The licence, the name, URL, description and use cases come from governance/ai_data.toml, and lib.ai_data.card_problems is the platform's own check of the result. Generate the card, first with mlcroissant's default conformsTo:

corpus-dataset-card.py Python 3.12.15 · datasketch 2.0.0 · duckdb 2.0.0 · mlcroissant 1.1.1 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · presidio-anonymizer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 通過
"""Generates the corpus's Croissant card twice, first with mlcroissant's default conformsTo and then as the platform writes it, and runs the platform's own check on it. The prose's point rests on the "conformsTo" lines and the "problems" line."""from lib import ai_datafrom lib.catalog import open_catalogbuilt = ai_data.build(open_catalog(["crm.learners", "learning.courses", "learning.reviews"]))# mlcroissant's default, then the card the pipeline writes, with Croissant 1.1 written out.# an empty list leaves conformsTo to mlcroissant, which writes its own defaultdefault, _ = ai_data.card(built, conforms_to=[])print("conformsTo, mlcroissant's default:", default["conformsTo"])# the card as the platform writes it: Croissant 1.1 and the RAI vocabulary, written outcard, warnings = ai_data.card(built)ai_data.write_card(card, built.folder)print("conformsTo, written out:", ", ".join(card["conformsTo"]))print("datePublished, the run's:", card["datePublished"])# the build's date as the major number: a nightly build may remove recordsprint("version, the run's:", card["version"])print("the sources the card names:", ", ".join(source["@id"] for source in card["prov:wasDerivedFrom"]))print("the tables that decided which rows, as the card names them:",      ", ".join(table["@id"] for table in card["prov:wasInfluencedBy"]))print("the activity the card names:", card["prov:wasGeneratedBy"]["prov:label"])# the card names every column of the corpus as a fieldprint("fields in the record set:", ", ".join(f["name"] for f in card["recordSet"][0]["field"]))for line in card["rai:dataPreprocessingProtocol"] + card["rai:personalSensitiveInformation"]:    print("-", line)# What mlcroissant reports, and what the platform's own check of the card reports.# the message after mlcroissant's severity tagprint("mlcroissant's warnings:", len(warnings))for warning in warnings:    print("- mlcroissant:", warning.split("] ", 1)[1])# the platform's own check: the library's validator doesn't report every requirementproblems = ai_data.card_problems(card, built.folder)print("problems the book's check finds:", len(problems))for problem in problems:    print("-", problem)
輸出python corpus-dataset-card.py
conformsTo, mlcroissant's default: http://mlcommons.org/croissant/1.0
conformsTo, written out: http://mlcommons.org/croissant/1.1, http://mlcommons.org/croissant/RAI/1.0
datePublished, the run's: 2026-10-01T02:00:00Z
version, the run's: 20261001.0.0
the sources the card names: iceberg://platform/learning.courses, iceberg://platform/learning.reviews
the tables that decided which rows, as the card names them: iceberg://platform/crm.learners
the activity the card names: platform/review_corpus
fields in the record set: review_id, course_id, course_title, rating, body, source_table, job, run_id
- Read 436 of 3,000 reviews, filtered on crm.learners.ai_training_consent, learning.reviews.learner_id.
- Replaced personal data with keyed pseudonyms (PERSON 120).
- Removed 340 exact duplicates and 0 near-duplicates (MinHash LSH, Jaccard similarity of 0.8 or more, confirmed exactly; 8 pairs that differ only in a name kept apart).
- Kept 96 records, each with its source table, review ID, job and run.
- Values replaced by keyed pseudonyms: PERSON 120.
- Emails and phone numbers replaced by [email] and [phone] by the enforcement layer's redact_contacts mask.
- Names found with a list of 106 words from crm.instructors, built by the governance team's job governance/instructor_names; the list isn't part of the corpus.
- Measured against labelled spans: 0 of 139 labelled values left in the text.
mlcroissant's warnings: 1
- mlcroissant: Property "http://mlcommons.org/croissant/citeAs" is recommended, but does not exist.
problems the book's check finds: 1
- creator: missing

Left to its default, mlcroissant writes http://mlcommons.org/croissant/1.0, although its own LATEST_VERSION is 1.1 (mlcroissant source), so a card would declare a version it wasn't written for. The platform writes http://mlcommons.org/croissant/1.1, http://mlcommons.org/croissant/RAI/1.0.

The card's datePublished, 2026-10-01T02:00:00Z, is the build's time, because the platform publishes a card only with the build it describes. Its version, 20261001.0.0, takes the build's date as its major number. Croissant recommends MAJOR.MINOR.PATCH, where a new major version means "the existing data has been changed (edited, removed or shuffled records across splits)", and any nightly build may remove records.

The card names the sources iceberg://platform/learning.courses, iceberg://platform/learning.reviews, the influence iceberg://platform/crm.learners and the activity platform/review_corpus, and lists preprocessing steps with the run's counts.

The warnings mlcroissant reports, 1 in all, are about recommended properties, here citeAs, not about the problem the platform's check finds: creator is missing. ai.review_corpus has no owner in the metadata file, the gap chapter 2 found, so the card stays unpublished until the table has an owner. Chapter 10 reports the same gap on every run, as a finding already on main.

mlcroissant can also read a card back, with mlc.Dataset, but at 1.1.1, with rdflib 7.6.0 and pandas 3.1.1, reading emits a DeprecationWarning from rdflib and a Pandas4Warning, and returns text fields as bytes. So the book's examples only write cards, and check them with the platform's own code.

Working rule: Generate the card in the run that builds the data, with every count, hash, source and version taken from that run, and write the format's version out. Check the card with your own code for every property the specification requires, since the library's validator doesn't report them all, and don't publish or train on a corpus whose card fails.

引述歐盟人工智慧法案對訓練資料的規定

最近一次變動於第 2026.11.27 版

歐盟的人工智慧法案(Artificial Intelligence Act),即歐盟規章 Regulation (EU) 2024/1689,在多處談到訓練資料。本節引述其中兩處,即第 10 條與第 53(1)(d) 條,我們對兩者都不加詮釋。

對於高風險人工智慧系統,第 10(2) 條規定,訓練、驗證與測試資料集「應受資料治理與管理實務所規範」,並列出這些實務所涉及的事項。其中包括資料蒐集流程與資料來源,以及蒐集個人資料的原始目的,還有資料準備作業,例如標註、標記、清理、更新、強化與彙整(人工智慧法案)。

第 10(3) 條要求資料集「具相關性、具足夠的代表性,並就預期目的而言,盡可能無錯誤且完整」(人工智慧法案)。

歐盟規章 Regulation (EU) 2026/1744,即人工智慧數位綜合修正案(Digital Omnibus on AI),於 2026 年 7 月 24 日公布,上述段落維持原引述內容不變。該規章替換第 10 條的第 1 項與第 6 項,刪除第 5 項,並新增第 4a 條「為偵測與修正偏誤而處理特殊類別個人資料」。它也訂定第 III 章第 1 至 3 節(包含第 10 條)的適用時點:對依第 6(2) 條與附件 III 歸類的高風險人工智慧系統,自 2027 年 12 月 2 日起適用;對依第 6(1) 條與附件 I 歸類者,自 2028 年 8 月 2 日起適用(歐盟規章 2026/1744)。

對於通用型人工智慧模型的提供者,第 53(1)(d) 條要求其「依人工智慧辦公室(AI Office)提供的範本,擬定並公開發布一份關於該通用型人工智慧模型訓練所用內容的足夠詳細之摘要」。歐盟執行委員會已將該範本以 C(2025) 8311 號文件發布(執行委員會範本、PDF)。

其說明通知指出,依該通知所列的執行委員會通用型人工智慧模型指引,下游單位若修改已投放於歐盟市場的模型,可能成為所產生模型的提供者。在此情況下,修改者只需申報用於該項修改的訓練內容。

該法案的附件 III 標題為「第 6(2) 條所稱之高風險人工智慧系統」,其第 3 點「教育與職業訓練」包括「(b) 擬用於評估學習成果的人工智慧系統,包括這些成果被用來引導各級教育與職業訓練機構中自然人之學習過程的情形」(人工智慧法案)。我們引述這一點,是因為該平台是教育平台,到此為止。該平台的任何系統依第 6 條是否屬於高風險,則是另一個問題,本章的程式碼都不取決於這個答案。

實用原則: 引述經修正後的法案,並以《官方公報》(Official Journal)為準,附上連結與你閱讀的日期,因為綜合修正案更動了條文與日期。不要把法律放進管線的邏輯中:卡片上的事實由執行過程產生,至於哪些條文適用,則交由負責回答法律問題的人決定。

正式環境中會出什麼問題

最近一次變動於第 2026.11.27 版

語料庫不會事先發出警告。模型完成訓練,模型卡也已發布,問題卻在之後才浮現:可能出現在模型的輸出中,也可能出現在一個無人能回答的請求裡。

此部分尚未翻譯,因此以英文呈現。

A learner withdraws after the build

最近一次變動於第 2026.11.27 版

Like marketing's list in chapter 7, a corpus records who had consented on the day it was built. Take the corpus that lib.ai_data.build writes in the nightly run of Oct 1, the Oct 1 build, and withdraw the consent of the author of one of its records. Then rebuild the corpus in the same folder the next night, without generating its card again, and check each build against today's consent, as a training run does before it starts:

The Oct 1 build holds 1 record by that learner, and the Oct 2 build holds 0, so the next corpus leaves the learner out. The two builds are different runs, with their own run IDs. The next training run has to leave the learner out too, and so does the next index.

Checked through provenance against today's answers, the Oct 1 build has 95 of 96 records whose author consents, so a training run that makes the check refuses it. The Oct 2 build passes with 95 of 95.

What was made from the Oct 1 build before the withdrawal keeps the review: a copy of its file, an index built from it, a model fine-tuned on it. The European Data Protection Board considers that "AI models trained with personal data cannot, in all cases, be considered anonymous" (EDPB Opinion 28/2024).

Article 7(3) of the GDPR gives the right to withdraw consent at any time. It says that withdrawing doesn't affect the lawfulness of processing based on consent before the withdrawal, that the person must be told of this right before giving consent, and that withdrawing must be no harder than giving it (GDPR). Chapter 7 quotes the first sentences of the same article and says what a withdrawal changes in the platform's code.

The code's part is to find, through provenance, every build that holds the record, and, by run ID, every model and index made from those builds. It then reads what happens to them from [legal.withdrawal] in governance/ai_data.toml. The legal team's answer for a model made from the Oct 1 build is undecided, a placeholder under which the job lists such models for the legal team and changes nothing. If the answer is that a model must not keep the review, the one way to remove it that we can vouch for is to train the model again on a build without it.

The card failed too, without a sound. Its last preprocessing step still reads "Kept 96 records, each with its source table, review ID, job and run." The file holds 95 records, and the platform's check finds 2 problems: the missing creator, and a file whose SHA-256 isn't the one the card states. A card that isn't generated again with its data describes another dataset.

Working rule: Record which build, by run ID, every model and index was made from. Before every training run, check the build's records against today's consent and the file's hash against its card, and refuse a build that fails either. When a learner withdraws, find the builds that hold their records and the models made from them, and let your legal team's answer in config decide what happens to those.

其他失敗情況

最近一次變動於第 2026.11.27 版
  • 保留「未知」的拒絕過濾器。 使用該過濾器建置時,語料庫收錄了 2,045 則評論,而非 436 則,其中多數來自從未被詢問過的學習者。要發現這個問題,可透過來源紀錄(provenance),依同意答覆統計語料庫的紀錄數:除了「是」以外的任何答覆都是缺陷。
  • 模型從其文字中記住的個人資料。 Carlini 等人從一個語言模型中擷取出訓練文字,其中包括姓名、電話號碼與電子郵件地址等公開的個人資訊,即使每一段這類序列都只出現在單一文件中(Carlini et al., 2021)。一般管線的語料庫含有 120 個已標記的電子郵件地址,其中 113 個互不相同,106 個只出現過一次,而重複內容會在每一份副本中重複偵測器漏掉的任何資訊。請以你自己文字的已標記樣本,衡量偵測後殘留的個人資料,並在訓練前先進行去重。
  • 外洩的假名金鑰。 只要有語料庫的金鑰和一份講師姓名清單,任何人都能算出語料庫中的每個假名。當金鑰可能已外洩時,應輪換金鑰、重建所有使用該金鑰製作的語料庫,並依執行 ID 找出以舊金鑰建置的版本所產生的副本與模型,做法與撤回同意時相同。

此部分尚未翻譯,因此以英文呈現。

What this chapter decided

最近一次變動於第 2026.11.27 版
  • The corpus is built through the enforcement layer, as analyst-1 for ai-training: only reviews whose author's ai_training_consent is true, contacts masked, an unknown consent counted as no.
  • Every legal answer the code needs is a placeholder for the legal team in [legal] in governance/ai_data.toml: the consent that admits a record, the card's licence, and what happens to models made before a withdrawal.
  • Personal data is detected after the enforcement layer's masks, with the pattern recognizers and the platform team's list of instructors' names, and replaced by keyed pseudonyms. Privacy Filter is measured, not added. The corpus is pseudonymized, never anonymized.
  • Pseudonyms are HMAC-SHA256 under the corpus job's own key, not the enforcement layer's SHA-256 over key and value, and never Presidio's randomly salted hash.
  • Duplicates are removed in two steps, exact copies by SHA-256, then near-duplicates from MinHash LSH tuned for 0.6 and confirmed at a Jaccard similarity of 0.8, never merging texts that differ only in a name. datasketch and its scheme, affine32, are pinned.
  • Every record keeps its provenance, source_table, review_id, job and run_id, and a training run checks its build against today's consent first.
  • The dataset card is Croissant 1.1 with RAI 1.0, generated by the run, checked by the platform's own code, and unpublished until ai.review_corpus has an owner.
  • Answers for one person come from an index of the corpus, filtered by that person's decision on each record's source review.
  • The EU AI Act is quoted as amended and linked, never interpreted. A corpus is only as clean as what was admitted into it. Each record is decided when the corpus is built, each record keeps its source, so a decision can be traced back to the review it came from, and the card says what was done with the rest.

本章,於本版次中

版次 2026.11.31範例於 2026年11 月 19 通過測試本章 10 個範例 個範例中有 10 個通過

譯自英文書,版次 2026.11.31。

引用本節

格式

各種格式皆引用英文原書,本譯本即依循該原書。

每種格式都會標示本版。其連結會開啟目前版次,節標題會說明該節內文最後一次變動的時間。存取日期與擷取日期即為你開啟此頁的當日。

本頁內容

第 9 章,共 10 章: 為 AI 治理資料

  1. Admit only reviews whose authors consented
  2. Replace personal data in the text, then measure what's left
  3. 以金鑰雜湊維持假名的一致性
  4. Find near-duplicates with MinHash
  5. Tune LSH for recall, then confirm every pair
  6. 讓每一筆記錄都帶有來源資訊
  7. Generate the dataset card from the run
  8. 引述歐盟人工智慧法案對訓練資料的規定
  9. 正式環境中會出什麼問題
  10. A learner withdraws after the build
  11. 其他失敗情況
  12. What this chapter decided

返回頂端所有章節