Skip to content

api-reference.ja.md

Latest commit

 

History

History
137 lines (111 loc) · 8.43 KB

api-reference.ja.md

File metadata and controls

137 lines (111 loc) · 8.43 KB
Raw

API リファレンス

English | 日本語

Vokra の API surface と、各リファレンスの所在の索引。大半はソースから 自動生成される。本ページは薄いポインタであって手管理のコピーではない （コピーは腐る）。何が生成で何が手書きかは §4 に記す。

1. Rust — docs.rs

Rust crate は rustdoc で documentation される。将来 crate が publish されると、 各 crate が自身のページへ auto-link される:

  • https://docs.rs/vokra-core — IR・Backend trait・GGUF loader・engine
  • https://docs.rs/vokra-capi — C ABI surface crate（IF-01）
  • https://docs.rs/vokra-models、.../vokra-ops、および backend crate 群

feature-gated な GPU/NPU バックエンドは [package.metadata.docs.rs] を持ち、 docs.rs がそのプラットフォーム固有 API をビルドする（Metal / CoreML は Apple target、WebGPU は wasm32、CUDA / Vulkan / QNN は各 feature 経由）。memory-safe な 単一 crate に絞ってローカルでビルドするには:

cargo doc -p vokra-core --no-deps --open

maintainer の workspace 全体 rustdoc は 16 GB の開発 Mac ではなく VAST / CI で 実行する。

2. C ABI — include/vokra.h

canonical な C リファレンスは生成済みヘッダ include/vokra.h である。scripts/gen-c-abi.sh が vokra-capi crate から生成し、その doc コメントがリファレンス本文となる。CI の drift check が Rust ソースとの同期を保つ。Unity / Godot / Swift / Kotlin / Python / JS の全バインディングはこの 1 つのヘッダの上に乗る（IF-01）。Vokra は 通常の Cargo crate / 単一ライブラリとして配布されるので、このヘッダ + ライブラリが統合 surface の全体である（NFR-DS-03）。

3. 言語バインディング

各バインディングは C ABI 上の慣用的な surface を自身で documentation する:

4. 何が自動生成で、何がそうでないか

  • 自動生成: Rust docs（rustdoc → docs.rs）と C ヘッダ（gen-c-abi.sh → include/vokra.h）。ソースから再生成され、source of truth である。
  • 手書きだが薄い: 本索引とバインディングチュートリアル。生成リファレンスと 動く例を指すだけで、API の 2 個目のコピーではない。
  • deferred（正直に）: C ヘッダの HTML 化（doxygen）と言語別 HTML ジェネ レータ（C# / Python / Swift の doc ツール）は未配線 — 当面はヘッダコメントと チュートリアルがリファレンス。初回の docs.rs render は crates.io publish 後に owner が確認する。

5. 現行 0.3.0 release と Apple 検証 status

現行の workspace release line は 0.3.0 である。

2026-10-17 current campaign snapshot: baseline main 5f1dfc1eには、 受理済みのmodel-free Candle CPU/API対応が含まれる。PR #259の通常CIは72成功・ 意図したskip1件で完了したが、追加observerパッチの実upstream library/API検証は 未実施のためDraftを維持する。最新の保持inventoryは10月16日の194 repositories、 136 code/artifact-full／58 non-fullである。この文書更新ではinventoryを再取得せず、 API/header再生成、実weight CPU、Apple parityの完了も主張しない。 現況と残タスクに、未マージ7 PRと 非Apple前提 → VAST → 最終packet → Scaleway → 結果記録・cleanupの順序をまとめる。 以下のhistorical snapshotは当時の範囲を保持する。

2026-10-13 metadata snapshot: exact GitHub main checkout は 7d38061c3dcb56f6a16bcf4b8085d966b3cdab09。fresh metadata/card-only audit は repository 194、GGUF repository 193、GGUF file 198 を報告している。 CPU は full=136、partial=43、no-runtime-binder=14、not-artifact=1、 Metal は full=136、blocked-by-cpu=57、not-artifact=1 である。 これは catalog metadata の更新であり、API/header や Apple 実機を再検証したものではない。 別途 2026-10-13 に実施した VibeVoice VAST audit は private な static-only audit で、 model や API を実行しておらず、CPU/Metal/no-fallback parity や公開可否を確立しない。 documentation refresh record と VibeVoice static-closure audit を参照すること。

2026-10-08 historical snapshot: 今回の documentation review と read-only metadata/card-only 公開 audit は GitHub の exact main checkout d100d93778191ccab77bd1c37fe3552e3d889758 を基準にしている。audit は repository 194、GGUF repository 193、GGUF file 198 を報告している。CPU status は full=136、partial=43、 no-runtime-binder=14、not-artifact=1、Metal status は full=136、 blocked-by-cpu=57、not-artifact=1 である。この historical snapshot では未解決の public row は58件だった。VibeVoice Realtime-0.5B は strict structural vibevoice_streaming binder と CLI inspection route に進み partial のままである。605-tensor の完全な checkpoint は変換済みで、 Microsoft source に対する狭い independent reference probe も受理済みだが、full streaming、 native CPU parity、Apple CPU/Metal 検証は未完了である。承認済みの Scaleway Apple CPU/reference、Metal/reference、no-fallback batch は named scope のみ合格し、その後、明示的に承認された4件の artifact が gated workflow 経由で 公開された。UTMOS numeric parity は未主張で、v0.3.0 release tag と GitHub Release は公開済みである。 2026-10-04 の修正済み VAST source-only audit は固定した Kyutai source input を認証し、 worker cleanup を独立に確認したが、model weight を実行せず、CPU、Apple hardware、公開 verdict は変更していない。 これは public model catalog 全体の対応完了や v1.0 release readiness を主張するものではない。

2026-09-09 audit-start historical snapshot: 監査開始時点の PR #79 head は 9efcd16eb63b857f48fc00d0b83d1113defd578b で、当時の remote check は成功 110、 想定 skip 13、失敗 0 である。監査開始時点の live public audit は 194 repository（GGUF repository 193、GGUF file 198）。CPU coverage は full=131、 partial=45、 no-runtime-binder=17、not-artifact=1、Metal は full=131、 blocked-by-cpu=62、not-artifact=1、source-level CPU-only は 0 である。 その監査開始時点の release tag は 0、GitHub Release も 0 である。

GigaAM v3 / Multilingual は conservative な Metal code route が complete だったが、 Apple hardware verdict は未取得。未解決の public row 63 件は complete と主張しない。 Scaleway は未開始であり、CI/audit 結果を Apple 実機 evidence の代用とはしなかった。 UTMOS の legacy Lightning checkpoint は制限付き weights_only=True loader が意図的に 拒否するため、numeric parity は主張しない。

Keeping this page current

最終確認日: 2026-10-08 — GitHub の exact main checkout d100d93778191ccab77bd1c37fe3552e3d889758 および include/vokra.h に対して 確認。 pre-alpha の Python generator と checked-in ctypes table は、生成 C の全 57 function と完全に一致する。header は 15 typedef、4 enum、2 concrete struct、9 opaque handle を持つ。高水準 Python package は、全 C handle に wrapper class を持つのではなく、より小さい慣用的な surface のままである。

  • 更新責任: publish crate・新バインディング・C ABI 生成を変えた PR が、 同一 PR で本索引と英語版を更新する。
  • review cadence: 四半期 Go/No-go review（NFR-MT-05）。
  • 生成 surface の再取得:
scripts/gen-c-abi.sh
# maintainer の workspace rustdoc は開発 Mac ではなく VAST/CI で実行:
cargo doc --no-deps --workspace