← Về thư mục
📄 / / proc / 45 / cwd / root / .hermes / skills-backup-20260914-152439 / devops / model-router-profile-mapping / SKILL.md

name: model-router-profile-mapping description: "Design, verify, stage, and roll out per-profile model pools in an OpenAI-compatible multi-provider router such as 9Router. Use when mapping Hermes profiles to router combos, validating exact model IDs, or testing a staged profile rollout." version: 1.0.0 author: CEO AI OS created_by: agent

Profile-to-Model-Router Mapping

Trigger

Use for configuring or reviewing profile-specific model routing where Hermes profiles call an OpenAI-compatible router that exposes named combos and models from multiple providers.

Operating model

Use a direct, simple structure unless the router explicitly requires another one:

Hermes profile → exactly one named router combo → ordered JSON list of exact model IDs

A model ID may appear in several profile combos. Do not introduce shared or nested “mixing” combos merely to enable reuse. Reuse is achieved by placing the same exact model ID in multiple combo arrays.

Source-of-truth rule

  1. Fetch the router's authenticated /v1/models catalog immediately before generating a mapping.
  2. Treat returned IDs as the executable catalog. Preserve provider prefixes and version suffixes exactly.
  3. Treat a provider console list as entitlement evidence, but do not place a listed model in a combo until it is returned by the router or verified through the provider endpoint currently configured in the router.
  4. Do not invent normalized aliases, model IDs, provider prefixes, or omit dated variants without saying so.

Provider quota vetting (upstream rate limits)

A model appearing in the router's /v1/models catalog does NOT mean it is usable. The upstream provider (e.g., Google AI Studio, Alibaba) may have zero quota on certain models for the account keys configured in the router. A request to such a model will fail after the router selects it, wasting the fallback/retry.

Before finalising any profile mapping, vet each model against its upstream provider's actual quota/rate-limit page:

  1. For AG/Antigravity Gemini models: check https://aistudio.google.com/u/1/rate-limit (or the equivalent console). Models with RPM=0, TPM=0, and RPD=0 have no quota and must be excluded from all combos.
  2. For Alibaba Singapore: check the Alibaba Cloud console quota page per region and model tier.
  3. For OpenAI Codex (cx/): check the Codex usage dashboard.
  4. For OpenRouter free models: check the Free tier rate-limit page.

Categorise each model into one of three tiers and tag them in the mapping document:

Quota rating Criteria Action
✅ Usable RPM > 0 and RPD > 0 Keep in pool
⚠️ Throttled RPM ≥ 1 but very low (≤ 5) Keep but place after higher-quota models; document the throttle
❌ Zero-quota RPM = 0, TPM = 0, RPD = 0 Exclude from every combo; note the exclusion reason

Zero-quota models are harmful because: - The router may still list them and attempt fallback through the entire pool before failing. - They extend the fallback chain pointlessly, multiplying latency for every request. - A user hitting a zero-quota model gets a silent failure or cryptic error.

When the user provides a screenshot of the provider's rate-limit page, extract the quota table and cross-reference every router model against it before writing the mapping. Do not skip this step even for models that appear in the router's catalog — the router returns catalog entries regardless of quota availability.

See references/ai-studio-quota-vetting.md for an example rate-limit audit.

See references/ai-studio-quota-vetting-20260724.md for a real-world audit record of Google AI Studio quota data (2026-07-24) that resulted in exclusion of 5 zero-quota Gemini models from all profile pools.

Model classification

Classify all live models before allocation. Keep the raw catalog in a reference document.

  1. Heavy reasoning and long-context: max, thinking, large parameter, expert/review models.
  2. Code: coder, Codex, code-specialized third-party models.
  3. Vision: VL, OCR, native vision models.
  4. General writing: plus, flash, translation and language-tuned models.
  5. Fast and low-cost: flash, turbo, mini, free, small models.
  6. Exclude only models incompatible with standard text chat, such as ASR-only, speech-to-speech, realtime-only endpoints, captioners, and contact-center-specific endpoints. List exclusions explicitly with the reason.

Priority allocation

Allocate by the user's stated profile usage order, not evenly.

  1. Give the most-used, highest-complexity profiles first access to heavy reasoning, code, review, and vision models as applicable.
  2. Allow deliberate overlap across high-priority profiles for reliability and cross-checking.
  3. Keep low-traffic/general profiles on fast, balanced, low-cost pools unless the user explicitly assigns them premium capacity.
  4. Do not put premium models in low-priority pools merely to make the pool look balanced.

Required mapping deliverable

Before writing router DB state, create a Markdown file containing all of the following, with no ellipses or implied entries:

  1. Full live catalog, grouped by provider, with each exact model ID on its own line.
  2. Every profile combo, exact combo name, model count, and every exact ID in its ordered pool.
  3. Explicit exclusions and reasons.
  4. Coverage result: every chat-capable model assigned at least once or named as deliberately unassigned.
  5. An overlap statement explaining which models are reused and why.

Do not replace exhaustive lists with phrases such as “all models”, “etc.”, “...”, or abbreviated provider summaries when the user asks to inspect the mapping. The user will reject abbreviated output — every model ID must appear on its own - bullet line. No implied continuation (“+N more”) is acceptable even if the full list was shown earlier.

Router capability checks

Before rollout, verify rather than assume:

  1. Inspect combo schema. Confirm models accepts a JSON array of exact string IDs.
  2. In a rolled-back transaction, insert two temporary combos containing the same model ID. Confirm overlap is permitted and rollback leaves no residue.
  3. Verify the intended combo name is accepted by /v1/chat/completions.
  4. Send an authenticated smoke test using the combo name as model; record HTTP status and the concrete resolved upstream model in the response.
  5. Confirm model ordering semantics from router documentation/source if priority ordering is important. Do not claim order means priority or fallback without evidence.

Safe staged rollout

When the user asks to test one profile first:

  1. Read the current profile config and snapshot the target router DB/config file.
  2. Record the current state of all existing combos and profile defaults.
  3. Create or update only profile-<target-profile>.
  4. Change only the target profile's model.default and local router provider default_model fields.
  5. Do not alter the existing default combo or any other profile configuration unless explicitly authorized.
  6. Smoke test model: profile-<target-profile> through the router.
  7. Verify all non-target profiles still point to default or their prior model.
  8. Report exact scope, backup paths, model count, HTTP result, resolved model, and remaining caveats.

Hermes profile configuration

For a profile-specific combo with provider local9router, ensure the target profile config uses:

model:
  provider: local9router
  default: profile-<profile-name>
providers:
  local9router:
    default_model: profile-<profile-name>

If the config includes a duplicate profile-named provider block, update it only within the target profile config and document why. Do not change auxiliary vision routing unless asked.

Additionally, when deploying multiple profiles, ensure that every profile config file (e.g., ~/.hermes/profiles/<name>/config.yaml) is modified to point its model.default and custom_providers.local9router.default_model fields to its designated combo, rather than leaving them pointed to the general default combo.

Profile Allocation Strategy (User Preferences)

These rules are non-negotiable — the user has explicitly corrected deviations. Do not deviate silently.

  1. Writers: MUST include large-parameter heavy models (Qwen Max, DeepSeek V4 Pro, Qwen3.5-397B, Qwen3.5-122B, Claude Opus, etc.) for rich Vietnamese language and long-context drafting. Assigning only Plus/Flash/light models to writers is WRONG — this error was corrected in session; do not repeat it.
  2. Reviewer: Same as Writers — must have latest, largest-parameter models. Context length is critical. Both Writers and Reviewer are the highest consumers of Vietnamese language fidelity.
  3. IT-AI: Must retain heavy architecture and system-design models (Qwen 3.7 Max series, thinking models, GLM 5.x) even if called infrequently. Architecture tasks justify the cost.
  4. r-and-d + grill-qa: Must keep all AG models (Claude Opus/Sonnet/GPT-OSS) plus full heavy Alibaba pool. Diversity is required for research synthesis and adversarial critique.
  5. Alibaba Singapore model list: Must be preserved exactly as agreed. Do NOT drop or add Alibaba models without explicit approval. The agreed list in references/profile-model-mapping.md is the source of truth.
  6. default + bd-mkt: Light, fast, cost-efficient pools only. Premium heavy models must NOT appear here unless explicitly requested.
  7. Priority Order for Model Selection: When mapping model pools, prioritize the models in this exact order:
  8. Tier 1: ag/* (Antigravity non-Claude models: gemini-, gpt-oss-)
  9. Tier 2: openai-compatible-alibaba/* (Qwen, DeepSeek, GLM series)
  10. Tier 3: ag/claude-* (Antigravity Claude models: claude-opus, claude-sonnet)
  11. Tier 4: cx/* (Codex GPT-5.x series)
  12. Tier 5: gemini/*, openrouter/* (direct Gemini API, OpenRouter free tier)

This ordering reflects cost, availability, and performance preferences. AG's distributed quota is preferred over paid Alibaba, which is preferred over AG's Claude (limited quota), which is preferred over Codex (paid).

⚠️ Common mistake: When asked to "optimize" or "rebalance" mappings, do not silently downgrade Writers or IT-AI to light models. Always enumerate proposed changes and confirm before applying.

User expectations

  1. The user will reject any deliverable that uses "..." or "etc." or "+N more" in a model list, even when the full list exists elsewhere in the same document. Every mapping MUST enumerate each model ID on its own line with zero truncation.
  2. When the user provides a console screenshot as source, treat it as entitlement evidence but verify each model ID against the router's live catalog before deploying.
  3. The user prefers staged rollout: one profile at a time, with explicit database/config backup paths and a smoke test before touching the next profile.

Pitfalls

  1. Docker/UI Database Mismatch: 9Router UI might appear empty if you edit /root/.9router/db/data.sqlite on the host, but the docker container mounts the database from a different volume or caches database state in-memory. Ensure you run docker inspect <container> to trace the volume binding (e.g., /root/.9router -> /app/data), run your updates directly on the mounted database path, and execute docker restart <container> to flush the cache.
  2. Combo Kind/Strategy Values: The database field kind in the combos table represents the routing strategy. If UI shows "No combos yet" or behaves unexpectedly, verify if the kind string value matches the UI expectation (e.g., default, fallback, round-robin, fusion). A mismatch in the kind enum/string can cause UI render failures.
  3. Do not modify an existing default combo while staging a target profile. It can interrupt all other profiles still using it.
  4. A self-reference such as "default" inside the default combo's own model array is a separate cleanup item. Do not repair it during a scoped staging test unless authorized.
  5. A successful HTTP response may be streamed or lack a conventional content-type header. Parse body behavior defensively and repeat with stream: false if necessary.
  6. Model lists copied from UI can contain IDs unavailable to the deployed router. Verify live availability before deployment.
  7. Do not claim router model array order provides weighted routing, priority, round robin, or fallback without code/documentation evidence.
  8. Never expose API keys in mapping reports, logs, backups, or links.

Reference

See references/9router-hermes-staged-rollout.md for a validated staged rollout and verification record.