sync: merge upstream/master into master / 同步上游 upstream/master 到 master

.claude/skills/ingest-run/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ingest-run
+description: Ingest one vngcloud/InferenceX GitHub Actions benchmark run into this fork's self-hosted prod DB, over SSH into the deploy host. Use whenever asked to "ingest this run", given a vngcloud/InferenceX actions/runs/<id> URL, or asked to get benchmark data from a workflow run into the dashboard. NOT for the upstream SemiAnalysisAI/InferenceX-app Neon-DB flow (a different agent/env covers that).
+---
+
+# Ingest one benchmark run (this fork, self-hosted host)
+
+This fork does **not** use Neon. Prod is a self-hosted docker-compose stack on a
+single runner host, with its own dockerized Postgres. That changes the ingest
+mechanics vs. the upstream project's docs — follow this skill, not generic
+`admin:db:ingest:run` examples you find elsewhere in the repo/docs.
+
+## Environment (fixed facts about this deployment)
+
+- **Deploy host**: `ssh -p 234 hoanq333@61.28.228.19`
+- **Prod compose project**: `/opt/docker-compose/docker-compose.yml`, services
+  `inferencex-app-1`, `inferencex-postgres-1` (local Postgres, NOT Neon), `inferencex-nginx-1`,
+  `inferencex-certbot-1`.
+- **Source repo for runs**: `vngcloud/InferenceX` (not `SemiAnalysisAI/InferenceX`).
+- **`DATABASE_WRITE_URL`** on this host points at the local `postgres` compose service.
+  It does **not** speak TLS — every `bun run admin:db:*` command below **MUST** pass
+  `--no-ssl`, or you get a confusing `Client network socket disconnected before secure TLS
+connection was established` / `ECONNRESET` error that looks like network flakiness but
+  isn't. `deploy.yml`'s own migration step already does this (`admin:db:migrate --yes --no-ssl`).
+- Dev stack (`inferencex-dev`, port `:8080`) is a separate, isolated compose project on the
+  same host — this skill is about **prod**.
+
+## Step 0 — confirm the run is actually finished
+
+```bash
+gh api repos/vngcloud/InferenceX/actions/runs/<RUN_ID> --jq '{name,status,conclusion}'
+```
+
+If `status` isn't `completed`, wait — do not attempt to ingest a partial run. Re-check later
+(a `ScheduleWakeup`/poll loop, not tight retries).
+
+## Step 1 — check whether the model/GPU/precision/framework is already registered
+
+Read the run's job names and artifact names (`gh run view <RUN_ID> --repo vngcloud/InferenceX`,
+not `--log`) and check whether the model prefix, hardware key, precision, and framework already
+resolve in the codebase (`packages/constants/src/models.ts` `DB_MODEL_TO_DISPLAY`,
+`packages/constants/src/gpu-keys.ts` `HW_REGISTRY`, `packages/db/src/etl/normalizers.ts`
+`PRECISION_ALIASES`/`MODEL_TO_KEY`). **If anything is new, follow
+`docs/adding-entities.md` first** — ingesting before the mapping lands means the DB silently
+skips those rows (no error, no partial write — the ETL just drops what it can't resolve). Commit,
+push to `master`, and wait for `deploy.yml` to finish (`gh run watch <run-id>`) before proceeding —
+the new mapping has to actually be in the container's code for ingest to pick it up.
+
+## Step 2 — download artifacts once, persistently, inside the container
+
+The artifact-download step and the DB write step both go over flaky links from this host
+(GitHub's artifact CDN, and TLS-handshake resets from the app container to the local Postgres
+under load). Don't repeat `--download` end-to-end on every retry — it wastes time re-fetching
+30+ artifacts just to retry the DB half. Split it:
+
+```bash
+ssh -p 234 hoanq333@61.28.228.19 \
+  "cd /opt/docker-compose && docker compose exec -T app sh -c \
+   'mkdir -p /tmp/ingest-<RUN_ID> && cd /tmp/ingest-<RUN_ID> && gh run download <RUN_ID> -R vngcloud/InferenceX && ls | wc -l'"
+```
+
+Confirm the artifact count matches what `gh run view` listed before moving on.
+
+## Step 3 — ingest in CI mode against the local artifacts (retry this, not the download)
+
+```bash
+ssh -p 234 hoanq333@61.28.228.19 \
+  "cd /opt/docker-compose && docker compose exec -T \
+   -e INGEST_RUN_ID=<RUN_ID> -e INGEST_RUN_ATTEMPT=1 \
+   -e INGEST_ARTIFACTS_PATH=/tmp/ingest-<RUN_ID> -e INGEST_REPO=vngcloud/InferenceX \
+   -e UNMAPPED_ENTITIES_OUTPUT=/tmp/unmapped.json \
+   app bun run admin:db:ingest:ci --no-ssl"
+```
+
+If it fails with the TLS/ECONNRESET error above, that's the local-Postgres connection blip, not
+a real problem with the data — just retry this exact command a few times. Do NOT switch to
+`admin:db:ingest:run <id> vngcloud/InferenceX` (the one-shot download+ingest command) as your
+retry loop; that re-downloads everything each time.
+
+Note the positional-arg gotcha if you ever do use the one-shot form: it's
+`admin:db:ingest:run <RUN_ID> <owner/repo>` — **positional**, not `--repo <owner/repo>`. Passing
+`--repo` makes the script try to parse `--repo` itself as a run ID and fail immediately.
+
+Watch the summary block at the end for `+N new, M duplicate` counts per data type (benchmark
+results, run stats, eval results, eval samples, changelog entries). `0 new, N duplicate` for a
+run you know was already ingested is expected, not an error.
+
+## Step 4 — overrides, verify, invalidate
+
+```bash
+ssh -p 234 hoanq333@61.28.228.19 "cd /opt/docker-compose && docker compose exec -T app bun run admin:db:apply-overrides --yes --no-ssl"
+ssh -p 234 hoanq333@61.28.228.19 "cd /opt/docker-compose && docker compose exec -T app bun run admin:db:verify --no-ssl"
+ssh -p 234 hoanq333@61.28.228.19 "cd /opt/docker-compose && docker compose exec -T app bun run admin:cache:invalidate http://localhost:3000"
+```
+
+`apply-overrides` reporting everything as "not in DB, skipping" is normal — most registry entries
+in `run-overrides.ts` target other runs. `db:verify`'s "Sample Rows" section is the fastest way to
+eyeball that the new config/benchmark_results rows look right (correct model key, precision,
+hardware, throughput numbers in a sane range).
+
+## Cleanup
+
+```bash
+ssh -p 234 hoanq333@61.28.228.19 "cd /opt/docker-compose && docker compose exec -T app rm -rf /tmp/ingest-<RUN_ID> /tmp/unmapped.json"
+```
+
+## Don't forget
+
+- If Step 1 required a code change, that same PR/commit should have updated
+  `packages/app/src/lib/api-route-catalog.ts`'s digest for `models.ts` (there's a vitest guard
+  that fails the build otherwise — `bun run test:unit` will tell you which digest to recompute:
+  `python3 -c "import hashlib; print(hashlib.sha256(open('<file>','rb').read()).hexdigest())"`).
+- If the model/GPU should be selectable in the dashboard UI (not just stored), that's a
+  **separate, optional** follow-up: `Model`/GPU registry entries in
+  `packages/app/src/lib/data-mappings.ts`, `compare-slug.ts`, `compare-ssr.ts` — see
+  `docs/adding-entities.md`. Ask the user whether they want that now or the DB write is enough
+  for this pass.

.claude/skills/review-zh-copy/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: review-zh-copy
+description: Use when reviewing PRs or diffs that add or modify user-visible Simplified Chinese in InferenceX, including refactors and files whose names do not contain zh.
+---
+
+# Review Simplified Chinese copy
+
+## Operating mode: advisory
+
+Every finding produced by this skill is non-blocking. Do not label a Chinese-copy finding
+`BLOCKING`, submit a request-changes review for it, or otherwise hold another contributor's merge.
+Do not mention `@edwingao28` for a clean review, routine coverage, or an ordinary wording or
+naturalness suggestion. Report an ordinary finding without a CC. Mention `@edwingao28` only for a
+high-confidence semantic or factual error, changed attribution or speaker voice, or high-impact
+ambiguity that cannot be resolved from the source and context. Label that finding
+`Needs Chinese maintainer confirmation` and ask for review. It remains a suggestion while the
+Chinese maintainer decides whether any follow-up is needed.
+
+The Chinese maintainer makes the final wording decision and manually reviews every changed
+Chinese passage.
+
+## Editorial source of truth
+
+Read [docs/chinese-copy.md](../../../docs/chinese-copy.md) completely before reviewing. Apply its
+audience, surface-specific register, context-aware terminology, rewrite method, and checklist.
+
+Semantic fidelity and natural Chinese are independent gates. Every changed passage must pass
+both:
+
+- **Fidelity:** facts, scope, modality, metrics, numbers, links, product names, and attribution
+  retain the English source's meaning.
+- **Naturalness:** the result reads as original Chinese technical writing in the register of its
+  surface, without preserving English clause order or noun stacking.
+
+A fluent mistranslation fails fidelity. An accurate sentence shaped like English fails
+naturalness.
+
+## Find the complete review scope
+
+Review every added or modified user-visible Chinese passage in the complete diff against its
+actual base. Do not infer scope from filenames. Chinese may appear in:
+
+- `zh:` dictionaries inside otherwise English TypeScript or TSX files;
+- locale-aware ternaries and registry labels;
+- `/zh` routes, Chinese MDX, JSON, metadata, schema.org content, alt text, and captions;
+- tooltips, modals, controls, option labels, empty/loading/error states, and feature-gated UI.
+
+Include the full UI element or paragraph, not only the changed word or source line. When an
+English/Chinese dictionary entry changes, inspect both siblings even if only one side is in the
+diff. Do not report awkward pre-existing Chinese that the diff did not touch; record it separately
+if it matters to a later rollout.
+
+Exclude identifiers, test data that is not rendered, DB-stored benchmark content, logs, and code
+syntax unless the changed text is presented to a user.
+
+## Build context before judging
+
+For each passage, collect:
+
+1. the complete English source;
+2. the route, component, and UI surface;
+3. the surrounding heading, control, paragraph, or attributed quotation;
+4. the intended meaning in plain language;
+5. facts, qualifications, modality, metrics, links, names, and attribution that cannot change;
+6. rendered desktop and mobile context when width, hierarchy, or interaction affects wording.
+
+If no English source exists, say so. Infer intent from adjacent UI and product behavior, and lower
+confidence rather than inventing a source claim.
+
+## Review workflow
+
+For every changed passage:
+
+1. State the source intent without copying the English sentence structure.
+2. Evaluate fidelity. Reject additions, omissions, changed scope, stronger certainty, altered
+   metric definitions, or a changed speaker voice.
+3. Hide the old Chinese and draft from the stated intent.
+4. Evaluate naturalness without looking at the English. Check information order, sentence
+   structure, register, and established Chinese ML infrastructure usage.
+5. Compare the proposed rewrite with the source again.
+6. Check the complete rendered element or paragraph. A locally natural word can still be wrong in
+   its button, tooltip, metadata, marketing, technical-prose, or quotation context.
+
+Do not use fixed substitutions for contextual questions. In particular:
+
+- sentence length alone is not evidence of translationese;
+- technical English is not wrong merely because a Chinese equivalent exists;
+- one concept may need different wording in a UI action, prose, a unit, or an attributed quote;
+- established English technical terms and phrases that Chinese ML infrastructure engineers
+  normally use in English should remain English in first-party UI and technical prose; judge this
+  from real industry usage and the surface, not from a closed list. `warmup`, `seed`, and `offload`
+  are examples, not the whole category. Chinese-first explanations such as `预热（warmup）` remain
+  valid for a broader audience, and attributed quotations preserve the speaker's wording;
+- `您` is normally omitted in controls and tooltips but may be intentional in a respectful CTA;
+- #819 and other bulk-rewrite outputs are not automatic editorial ground truth; only their
+  separately verified mechanical cases may seed deterministic CI fixtures.
+
+## Report high-signal findings
+
+For each finding provide:
+
+- `file:line` and route or surface;
+- the exact English source and a one-sentence statement of its intent;
+- which gate failed: fidelity, naturalness, or both;
+- the specific defect and its user impact;
+- one complete suggested replacement, not an isolated word swap;
+- confidence and advisory severity.
+
+Do not report only “this reads awkwardly.” Stay silent when the existing wording is accurate,
+natural, and appropriate for its surface, even if another wording is also possible.
+
+End with coverage: list the changed Chinese surfaces reviewed and any surface that could not be
+rendered or whose English source could not be identified.

.claude/skills/write-inferencex-blog/iso_interactivity.py

@@ -7,7 +7,8 @@
 packages/app/src/components/inference/hooks/useInterpolatedTrendData.ts.
 
 Pipeline:
-  1. Build the upper-left Pareto frontier on (interactivity, throughput).
+  1. Build the upper-left Pareto frontier on (interactivity, throughput). For a
+     proportional metric, use the total/output/input throughput it scales.
   2. Sort the frontier by interactivity ascending.
   3. Build monotone cubic Hermite slopes (Steffen 1990 method, same as
      d3.curveMonotoneX) over the frontier knots for the metric of interest.
@@ -18,12 +19,18 @@
   6. Clamp the interpolated metric value to [min(ys), max(ys)] of the
      frontier to prevent cubic-spline overshoots above/below the data.
 
-Reciprocal metrics ($/M tok, J/token) are a special case: they are a per-chip
-constant divided by a throughput, so they are NOT splined independently. Two
-independent splines need not preserve `metric * throughput = constant` between
+Reciprocal metrics ($/M tok in blog tables, J/token) are a special case: they are
+a per-chip constant divided by a throughput, so they are NOT splined independently.
+Two independent splines need not preserve `metric * throughput = constant` between
 measured knots. Pass `reciprocal_of='throughput'` (or the matching output/input
-throughput key) to spline that throughput and re-derive the metric, which is what
-the dashboard does. See docs/tco-calculator.md for a reproducible measurement.
+throughput key) to spline that throughput and re-derive the metric. The live
+inference charts also expose tokens/$ and normalized token revenue as separate
+metrics; both are directly proportional to throughput. OpenRouter-priced revenue
+is proportional only when the input/output mix stays constant; otherwise spline
+the already-priced metric directly. Pass
+`proportional_to='throughput'` (or the matching output/input throughput key) so
+they use the same Pareto knots and spline as that throughput before applying the
+recovered multiplier. See docs/tco-calculator.md for a reproducible measurement.
 
 Usage as a module:
     from iso_interactivity import interpolate_metric, pareto_front_upper_left
@@ -182,38 +189,65 @@ def recover_reciprocal_numerator(
     return numerator
 
 
+def recover_proportional_multiplier(
+    values: list[Optional[float]], throughputs: list[Optional[float]]
+) -> Optional[float]:
+    """Recover the constant `k` of a metric defined as `throughput * k`."""
+    relative_tolerance = 1e-3
+    multiplier: Optional[float] = None
+    for value, throughput in zip(values, throughputs):
+        if value is None or throughput is None:
+            continue
+        if not value > 0 or not throughput > 0:
+            continue
+        candidate = value / throughput
+        if multiplier is None:
+            multiplier = candidate
+        elif abs(candidate - multiplier) > abs(multiplier) * relative_tolerance:
+            return None
+    return multiplier
+
+
 def interpolate_metric(
     points: list[dict],
     target_iv: float,
     metric_key: str = 'throughput',
     iv_key: str = 'interactivity',
     tput_key: str = 'throughput',
     reciprocal_of: Optional[str] = None,
+    proportional_to: Optional[str] = None,
 ) -> Optional[float]:
     """Interpolate `metric_key` at `target_iv` using the chart's algorithm.
 
     Returns None if target_iv is outside the frontier's [min_iv, max_iv] range —
     the chart code does not extrapolate. Blog tables should render this as
     `_unreachable_` in that row.
 
-    The Pareto frontier is ALWAYS built on (interactivity, throughput) regardless
-    of which metric you're interpolating — this matches the chart, where the
-    frontier is defined by the upper-left throughput envelope and other metrics
-    (cost, energy, TPOT, ...) are derived values at frontier points.
+    The Pareto frontier is built on (interactivity, throughput). For tokens/$ or
+    normalized token revenue (and revenue with a constant token mix),
+    `proportional_to` names the total/output/input
+    throughput it scales; that throughput also supplies the frontier knots so
+    both curves stay aligned.
 
     `reciprocal_of` names the throughput key a metric divides, for metrics of the
     form `constant / throughput` ($/M tok, J/token). Set it for those metrics:
     that throughput is splined and the metric re-derived, matching the dashboard.
     Leave it None for metrics splined directly (throughput itself, tok/s/MW,
     latency, and measured energy — whose numerator varies per point).
+
+    `proportional_to` names the throughput key for metrics of the form
+    `throughput * constant` (tokens/$, normalized token revenue, and revenue
+    with a constant input/output mix). That
+    throughput is splined and the recovered multiplier applied, matching the
+    dashboard.
     """
     if not points:
         return None
 
     frontier = pareto_front_upper_left(
         points,
         get_x=lambda p: p[iv_key],
-        get_y=lambda p: p[tput_key],
+        get_y=lambda p: p[proportional_to or tput_key],
     )
     if not frontier:
         return None
@@ -241,6 +275,19 @@ def interpolate_metric(
             return None
         ys.append(value)
 
+    if proportional_to is not None:
+        tputs: list[float] = []
+        for point in sorted_front:
+            throughput = point.get(proportional_to)
+            if throughput is None:
+                return None
+            tputs.append(throughput)
+        multiplier = recover_proportional_multiplier(ys, tputs)
+        if multiplier is not None:
+            tput_slopes = monotone_slopes(xs, tputs)
+            tput = hermite_interpolate(xs, tputs, tput_slopes, target_iv)
+            return max(0.0, tput) * multiplier
+
     if reciprocal_of is not None:
         tputs: list[float] = []
         for point in sorted_front:
@@ -276,7 +323,8 @@ def interpolate_metric(
 
 def _cli() -> None:
     """Stdin: {"points": [...], "target_iv": N, "metric_key": "...",
-               "reciprocal_of": "throughput" for $/M tok and J/token}
+               "reciprocal_of": "throughput" for $/M tok and J/token,
+               "proportional_to": "throughput" for tokens/$ or revenue with a constant mix}
     Stdout: {"value": N or null}"""
     req = json.loads(sys.stdin.read())
     value = interpolate_metric(
@@ -286,6 +334,7 @@ def _cli() -> None:
         iv_key=req.get('iv_key', 'interactivity'),
         tput_key=req.get('tput_key', 'throughput'),
         reciprocal_of=req.get('reciprocal_of'),
+        proportional_to=req.get('proportional_to'),
     )
     json.dump({'value': value}, sys.stdout)
     sys.stdout.write('\n')