語義影片管線核心概念
語義影片管線 是一個 TypeScript 應用程式,它協調 AI 驅動的影片分析服務,以從影片內容中提取、索引和檢索語義資訊。此管線以一個樹狀的類型化宣告進行配置,並透過 CLI 命令進行管理。
兩個基本原則主導一切:
- 您的程式碼絕不讀取其環境。 依賴項、配置、憑證和連接埠都透過服務節點以類型化方式送達。
process.env永遠不是答案。 - 管線從不打包或轉換您的程式碼。 您使用自己的打包工具進行建置;框架透過確定性步驟組裝建置輸出,並將其交給配置的部署目標。
宣告即資料
您編寫的一切都是宣告:描述應用程式一部分的純資料,匯入時不執行任何操作。存在三種節點類型:
| 類型 | 宣告方式 | 用途 |
|---|---|---|
| 服務 | compute() | 您程式碼的執行單元;原子性的,管線僅能看到其連接埠 |
| 資源 | rawPostgres(), bucket() | 有狀態的受管依賴項 |
| 模組 | module() | 分組邊界;不執行自己的程式碼,公開類型化的連接埠 |
節點透過連接埠連接:deps 宣告節點需要什麼,expose 宣告它提供什麼。接線發生在模組的建構器中,透過 provision(),而傳遞給 CLI 的根模組即為應用程式:
// module.ts
import { module } from '@prisma/composer';
export default module('store', ({ provision }) => {
const catalog = provision(catalogModule);
provision(storefrontService, { deps: { catalog: catalog.rpc } });
});
由於連接埠是類型化的,編譯器會驗證每一條線路。依賴項連接到了錯誤的生產者、缺少的 RPC 處理程式、形狀錯誤的字面輸入值:所有這些都會導致 tsc 失敗,而不是部署失敗。環境綁定的輸入是例外:這些值僅在部署時存在,因此秘密綁定不匹配和缺少的平台變數會作為早期的部署時拒絕而顯現(請參閱下方的雙通道)。先進行類型檢查,然後建置,最後部署;不要使用雲端來找出接線是否正確。
管線本身與目標無關:@prisma/composer 包含編寫、測試和 CLI,不與任何平台耦合。部署目標是在部署配置中註冊的擴展;@prisma/composer-prisma-cloud 是 Prisma Cloud 目標,也是本技能部署章節假設使用的目標。它的根導出 compute、rawPostgres、bucket、envSecret 和 envParam;ORM 詞彙(postgres、dataContract)位於 /orm 子路徑下,與共享的 /cron、/storage、/streams、/auth 和 /email 模組並列。這些是基礎 Prisma Cloud 應用程式需要的僅有的兩個 Composer 套件,並且沒有東西會為您安裝它們:一個新項目開始時兩者都沒有,所以首先將兩者都作為依賴項添加。擴展會在它們旁邊添加自己的 prisma-composer-* 套件。在自行實現某個功能之前,先組合一個現有的模組;接入一個模組只需要幾行程式碼。
在入口圖(從 module.ts 可達到的所有內容)內,使用帶有顯式 .ts 副檔名的相對導入(./service.ts,並在 tsconfig 中設定 allowImportingTsExtensions):該形式在所有地方都能解析。prisma deploy 和 prisma dev 也會將 ./service.js 和無副檔名的 ./service 映射到 .ts 原始檔,但其他工具可能不會。
服務節點是唯一的入口
您的執行時期程式碼從它導入的服務宣告中接收一切:
service.load():依賴項(類型化的 RPC 用戶端、資料庫綁定)。service.input():將整個輸入視為一個經過 schema 驗證的物件;其中的憑證是經過編輯的SecretString盒子。service.port():要綁定的保留連接埠(預設為 3000)。
服務宣告是純資料;伺服器入口是您的建置產生的,並由平台啟動:
// service.ts
export default compute({
name: 'auth',
deps: { db: rawPostgres() },
build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
expose: { rpc: authContract },
});
// server.ts
const { db } = service.load(); // { url }: 您建構自己的用戶端
const handler = serve(service, {
rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });
消費者宣告 deps: { auth: rpc(authContract) } 並從 load() 取得一個類型化的用戶端。
雙通道:依賴項和輸入
| 值是… | 宣告 | 提供 | 讀取 |
|---|---|---|---|
| 由另一個節點產生 | deps: { db: rawPostgres() } | 在 provision() 接線 | load() |
| 其他任何東西(配置或憑證) | input schema 的一個欄位 | 在 provision() 綁定:字面值、envParam() 或 envSecret() | input() |
服務宣告其整個傳入配置,明文值和憑證一起,作為一個 Standard Schema(arktype 是首選)。憑證是類型化為 secretString() 的欄位,來自 @prisma/composer/arktype;條件合法性(「除非計費開啟,否則無 stripe 金鑰」)是一個普通的 schema 聯合。provision() 的綁定反映了 schema 的形狀;envSecret('NAME') 命名平台變數,且永遠不攜帶值。
會造成問題的規則:
- 秘密性由驗證強制執行。 如果 schema 期望
SecretString,卻綁定了字面值,則會導致部署失敗;envSecret綁定到純字串欄位會以相同方式失敗。 envParam值以原始字串形式送達;將它們綁定到字串欄位。階段的平台變數是存儲;部署 shell 僅填入缺少的名稱(當兩者都缺少時,部署會提前失敗,並指出變數名稱)。更改平台值需要重新部署。- 缺失由 schema 決定。 環境綁定欄位,如果其變數未設定或為空,則解析為金鑰省略,這只有在 schema 允許時才合法(可選欄位、聯合分支)。部署報告會列印序列化的輸入文件(秘密以
{"$secret":"VAR"}指針形式存在)以及每個解析為缺失的金鑰。 - 保留的
port在 schema 外部。 透過service.port()讀取它,永遠不要用process.env。框架也為 Next.js standalone 匯出PORT,它會自己綁定它。 - 模組轉發秘密需求,而不需學習平台名稱。 在模組邊界宣告
secrets: { signingKey: secret() },並將轉發的引用作為綁定葉節點傳遞;父模組綁定實際來源。 input.apiKey.expose()是取得秘密值的唯一方法;盒子在其他所有地方都會進行編輯(日誌、JSON、錯誤)。
合約與 RPC
合約是服務之間通訊的類型化介面。它與擁有它的服務一起存在,由任何 Standard Schema 驗證器類型化,提供者(serve(),在編譯時窮舉合約的方法)和消費者(rpc(contract))都引用同一個值。呼叫作為 RPC 透過 HTTP 傳輸。有兩個行為是為您佈建好的,且不得重新實作:
- 服務金鑰。 在部署時,Composer 為每個消費者→提供者綁定鑄造一個獨特的不可猜測的金鑰;
serve()在處理程式運行之前,對任何其他請求返回401。您的程式碼中沒有東西宣告它。後果:不要建立您自己的服務對服務認證,也不要使用curl訪問已部署的/rpc/<method>來檢查它是否正常運作。未接線的呼叫者總是會得到401,這看起來像是部署失敗,但其實不是。透過消費者進行除錯,或在本地進行(本地不強制執行任何東西)。金鑰是按綁定劃分的(一個金鑰洩漏無法冒充另一個消費者)、服務作用域(任何有效的金鑰都能到達每個方法;拆分服務以單獨保護)、只能透過移除綁定或銷毀堆疊並重新部署來輪替,並儲存在部署擁有的COMPOSER_*變數中,您永遠不應手動編輯。 - 冪等性和重試。 每個生成的用戶端呼叫都帶有一個
Idempotency-Key;丟棄的呼叫會以退避方式重試,而serve()對每個金鑰運行一次呼叫,將已完成的答案重放給延遲的重試。因此,每個方法都是安全可重試的,並且沒有合約宣告與此相關的任何內容(沒有「這是冪等的嗎」標誌;不要發明一個)。處理程式可以接受一個可選的第三個參數(input, deps, ctx)並讀取ctx.idempotencyKey(string | undefined),如果它需要在某個實例的記憶體之外實現恰好一次語義;大多數不需要。在本地和測試中,沒有佈建任何東西,因此serve()會讓所有呼叫通過:永遠不要在測試輸入中提供金鑰。
建置是您的
您建置,框架組裝。對於一個普通的伺服器程序,entry 必須指向一個單一的、自包含的 ESM 檔案:除了執行時期內建(bun、bun:*、node:*)之外的所有內容都內聯。部署會複製那個單一檔案,並且永遠不會傳送 node_modules,因此任何未內聯的內容都會在啟動時失敗,而不是在部署時。會造成問題的規則:
- 一個套件中的兩個服務意味著兩個獨立的建置,每個入口一個。單一的多入口建置會將共享程式碼拆分到兩個輸出都不包含的區塊中。
- 目錄建置使用
dir+entry(dir相對於服務模組,entry是dir內部的檔案;../是一個錯誤)。樹狀結構會被逐字複製,因此伺服器必須相對於import.meta.url解析同級檔案,而不是相對於工作目錄。樹狀結構不能包含符號連結:打包器會拒絕它們,指出連結名稱,然後組裝失敗。 - Next.js:帶有
output: 'standalone'的next build是整個建置;nextjs({ module, appDir })指定應用程式根目錄。任何呼叫load()的頁面或動作都需要export const dynamic = 'force-dynamic',因為執行時期環境在建置時不存在,而 Next 會忽略預先渲染路由的執行時期環境。 - 在
deploy或dev之前務必先建置。 兩者都不會為您建置。
部署配置是 prisma.config.ts 的 composer 部分,僅此而已。它註冊擴展(當應用程式有 Next.js 服務時,為 prismaCloud()、nodeBuild()、nextjsBuild())以及部署狀態後端(prismaState()):
// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';
export default definePrismaConfig({
composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});
命令會從它們運行的目錄開始尋找 prisma.config.ts,向上遍歷到儲存庫根目錄;宣告了 composer 的最近檔案獲勝,並且其部分會被完整使用,絕不會逐個金鑰合併。只允許 extensions 和 state;任何其他金鑰都是錯誤。應用程式程式碼絕不導入此檔案。
一個單獨的 prisma-composer.config.ts 不再被讀取,舊的設定會被拒絕,絕不會被靜默忽略:當沒有載入的 prisma.config.ts 宣告 composer 部分時,出現 CONFIG.SECTION_MISSING;當該部分仍然有 configPath 時,出現 CONFIG.FIELD_RETIRED;當 prisma-composer.config.* 位於宣告 prisma.config.ts 旁邊時,出現 CONFIG.FILE_RETIRED;所有三個都在 CLI 的 CLI.CONFIG_SECTION_INVALID 之下。所有三個的修復方法是將舊檔案的 extensions 和 state 移動到該部分,並刪除舊檔案。@prisma/composer-cli/family 不再匯出 ComposerSection;該部分的類型是來自 @prisma/composer/config 的 PrismaAppConfig。
資料庫與遷移
兩種 Postgres 依賴項:
rawPostgres():綁定是{ url },應用程式擁有自己的用戶端。postgres(...):一個 Prisma-ORM-類型化的資料庫。綁定是{ url, client }(ADR-0040):原始連接 URL 加上 Composer 從您的資料合約建構的類型化用戶端,在首次訪問時惰性初始化,因此查詢透過binding.client進行,並在編譯時檢查。postgres和dataContract都從@prisma/composer-prisma-cloud/orm導入,而不是從套件根目錄導入。一個dataContract包裝的值(由prisma contract emit從contract.prisma發出)被依賴端(deps: { db: postgres(catalogData) })和資源端引用,資源端也指定prisma.config.ts路徑,以便部署的遷移步驟可以重新載入已發出的contract.json並找到migrations/。
部署僅是重放:它們套用已提交到 migrations/ 下的遷移,並且從不自行建立 schema。每個 schema 更改,包括新資料庫的第一個 schema,都遵循一個循環:
- 編輯
contract.prisma。 prisma contract emit重新產生contract.json+contract.d.ts。prisma migration plan --name <slug>撰寫遷移(在空的圖表上,這會撰寫基準)。- 提交變更後的
migrations/,然後部署。一個全新的資料庫會從空開始重放整個路徑。
每個使用該資料庫的服務僅在其遷移完成後才會部署:遷移失敗意味著新程式碼不會發布。舊程式碼在舊的 schema 上提供服務,直到新部署上線,因此請保持每個遷移與其替換的程式碼相容。
如果沒有撰寫的路徑能達到目標合約,部署(以及針對過時本地資料庫的 dev)會拒絕,並顯示 MIGRATION_PATH_NO
…
[為翻譯而截斷]