{ "openapi": "3.0.3", "info": { "title": "whichllm API", "description": "GPU/LLM 硬件排行榜与模型匹配查询服务。查询你的硬件适合跑哪个本地大模型。\n\nGPU/LLM hardware ranking and model matching service. Find out which local LLM fits your hardware.", "version": "1.0.0", "contact": { "url": "https://github.com/Andyyyy64/whichllm" } }, "servers": [ { "url": "https://whichllm.net", "description": "Production" } ], "paths": { "/api/rankings": { "get": { "summary": "排行榜总览", "description": "Paginated rankings with multi-field filtering and multi-column sorting.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "每页条数" }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "all", "enum": [ "all", "general", "coding", "vision", "math" ] }, "description": "使用场景" }, { "name": "category", "in": "query", "schema": { "type": "string", "default": "all", "enum": [ "all", "consumer", "workstation", "datacenter" ] }, "description": "硬件类别" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "GPU 名称关键词搜索" }, { "name": "min_score", "in": "query", "schema": { "type": "number", "default": 0 }, "description": "最低分数过滤" }, { "name": "vram_min", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "最小显存(GB)" }, { "name": "vram_max", "in": "query", "schema": { "type": "integer", "default": 999 }, "description": "最大显存(GB)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "r", "enum": [ "g", "v", "c", "p", "r", "m", "s", "sp", "lk", "dl" ] }, "description": "排序列" }, { "name": "dir", "in": "query", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] }, "description": "排序方向" } ], "responses": { "200": { "description": "Ranking rows with pagination metadata" } } } }, "/api/rankings/nearby": { "get": { "summary": "VRAM 相近的 GPU 排名", "description": "Find GPUs with similar VRAM and their rankings.", "parameters": [ { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "gpu_id", "in": "query", "schema": { "type": "string" }, "description": "GPU ID as reference" }, { "name": "min_score", "in": "query", "schema": { "type": "number", "default": 0 } }, { "name": "max_score", "in": "query", "schema": { "type": "number", "default": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Nearby GPU rankings" } } } }, "/api/models": { "get": { "summary": "GPU 模型列表", "description": "List models compatible with a specific GPU.", "parameters": [ { "name": "gpu", "in": "query", "required": true, "schema": { "type": "string" }, "description": "GPU name keyword" }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Model list for the GPU" } } } }, "/api/models/{id}": { "get": { "summary": "模型详情", "description": "Get model details and its performance across all GPUs.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model ID (e.g. Llama-3-70B)" } ], "responses": { "200": { "description": "Model details with GPU compatibility list" } } } }, "/api/models/related": { "get": { "summary": "替代模型推荐", "description": "Find alternative models with similar VRAM requirements.", "parameters": [ { "name": "model_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Related models list" } } } }, "/api/models/enrich": { "post": { "summary": "模型元数据同步（管理）", "description": "Fetch model metadata (likes/downloads) from HuggingFace API.", "responses": { "200": { "description": "Enrichment result with counts" } } } }, "/api/reverse": { "get": { "summary": "反向查询", "description": "Find which GPUs can run a given model.", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Model name keyword" }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "GPU list for the model" } } } }, "/api/hot": { "get": { "summary": "热门排行", "description": "Top-ranked model per GPU (rank=1) sorted by score.", "responses": { "200": { "description": "Hot ranking cards" } } } }, "/api/kpi": { "get": { "summary": "关键指标", "description": "Key metrics: top score, hardware count, total configs, row count.", "responses": { "200": { "description": "KPI overview" } } } }, "/api/autocomplete": { "get": { "summary": "GPU 自动补全", "description": "Autocomplete GPU names.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Search keyword" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 20 } } ], "responses": { "200": { "description": "Autocomplete suggestions" } } } }, "/api/search": { "get": { "summary": "全文搜索", "description": "Full-text search across GPU and model names.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Search results" } } } }, "/api/search/log": { "post": { "summary": "搜索日志记录", "description": "Log search queries for trending analysis.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "profile": { "type": "string", "default": "general" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Logging result" } } } }, "/api/trends": { "get": { "summary": "趋势数据", "description": "30-day score and popularity trends.", "responses": { "200": { "description": "Trend data" } } } }, "/api/trend": { "get": { "summary": "单 GPU 趋势", "description": "Score trend for a single GPU.", "parameters": [ { "name": "gpu", "in": "query", "required": true, "schema": { "type": "string" }, "description": "GPU ID" }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30 } } ], "responses": { "200": { "description": "GPU trend data" } } } }, "/api/trending": { "get": { "summary": "热门搜索趋势", "description": "Top search queries in the last 7 days.", "responses": { "200": { "description": "Trending search queries" } } } }, "/api/meta": { "get": { "summary": "元数据", "description": "Last update timestamp of ranking data.", "responses": { "200": { "description": "Update metadata" } } } }, "/api/detect": { "post": { "summary": "GPU 检测", "description": "Submit hardware info for GPU matching and model recommendations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "gpu_name": { "type": "string", "description": "GPU name (e.g. RTX 4090)" }, "gpu": { "type": "string", "description": "Alias for gpu_name" }, "vram_gb": { "type": "number", "description": "VRAM in GB" }, "ram_gb": { "type": "number", "description": "System RAM in GB" }, "os": { "type": "string", "description": "Operating system" }, "profile": { "type": "string", "default": "general" } } } } } }, "responses": { "200": { "description": "Detection result with model recommendations" } } } }, "/api/export": { "get": { "summary": "数据导出", "description": "Export data in JSON, NDJSON, or CSV format.", "parameters": [ { "name": "profile", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "default": "json", "enum": [ "json", "ndjson", "csv" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5000, "maximum": 10000 } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated field list" } ], "responses": { "200": { "description": "Exported data" } } } }, "/api/leaderboard": { "get": { "summary": "排行榜精简版", "description": "Condensed leaderboard: rank=1 GPUs for a profile.", "parameters": [ { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Leaderboard entries" } } } }, "/api/top-per-category": { "get": { "summary": "各类别 Top-3", "description": "Top 3 rank-1 GPUs per category.", "parameters": [ { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } } ], "responses": { "200": { "description": "Top per category" } } } }, "/api/compare": { "get": { "summary": "GPU 对比", "description": "Compare two GPUs' model performance.", "parameters": [ { "name": "gpu1", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "gpu2", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } } ], "responses": { "200": { "description": "Comparison result" } } } }, "/api/similar": { "get": { "summary": "VRAM 相近 GPU", "description": "Find GPUs with similar VRAM capacity.", "parameters": [ { "name": "gpu", "in": "query", "required": true, "schema": { "type": "string" }, "description": "GPU ID" }, { "name": "margin", "in": "query", "schema": { "type": "integer", "default": 4 }, "description": "VRAM tolerance (GB)" } ], "responses": { "200": { "description": "Similar GPUs" } } } }, "/api/stats": { "get": { "summary": "全局统计", "description": "Full statistics: overview, by-profile, top/bottom 10.", "responses": { "200": { "description": "Statistics" } } } }, "/api/stats/summary": { "get": { "summary": "统计摘要", "description": "Condensed stats: model/gpu counts, avg/max score.", "responses": { "200": { "description": "Stats summary" } } } }, "/api/stats/monitor": { "get": { "summary": "监控数据", "description": "KV cache hit rate + D1 latency monitoring.", "responses": { "200": { "description": "Monitoring data" } } } }, "/api/stats/distribution": { "get": { "summary": "分布统计", "description": "Score/profile/VRAM distribution statistics.", "responses": { "200": { "description": "Distribution data" } } } }, "/api/categories": { "get": { "summary": "分类总览", "description": "Category overview with GPU/model counts and avg scores.", "responses": { "200": { "description": "Category overview" } } } }, "/api/changelog": { "get": { "summary": "更新日志", "description": "Latest changelog entry.", "responses": { "200": { "description": "Latest changelog" } } } }, "/api/history": { "get": { "summary": "日志历史", "description": "Changelog history list.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "History entries" } } } }, "/api/upgrade": { "get": { "summary": "升级路径", "description": "VRAM upgrade path from a given GPU.", "parameters": [ { "name": "gpu", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "profile", "in": "query", "schema": { "type": "string", "default": "general" } } ], "responses": { "200": { "description": "Upgrade path" } } } }, "/api/profile-compare": { "get": { "summary": "跨场景对比", "description": "Single GPU comparison across all profiles (general/coding/vision/math).", "parameters": [ { "name": "gpu", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cross-profile comparison" } } } }, "/api/vram/estimate": { "get": { "summary": "VRAM 估算", "description": "Estimate VRAM usage for a model at different quantization levels.", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "quant", "in": "query", "schema": { "type": "string" }, "description": "Quantization filter (e.g. Q4_K_M)" } ], "responses": { "200": { "description": "VRAM estimates" } } } }, "/api/all": { "get": { "summary": "全部原始数据", "description": "All raw ranking rows (no pagination).", "responses": { "200": { "description": "All data rows" } } } }, "/api/d1": { "get": { "summary": "D1 诊断（管理）", "description": "D1 database diagnostics (internal).", "responses": { "200": { "description": "DB diagnostics" } } } }, "/api/validate": { "get": { "summary": "数据校验", "description": "Data integrity checks.", "responses": { "200": { "description": "Validation results" } } } }, "/api/docs": { "get": { "summary": "API 文档", "description": "Structured JSON documentation for all endpoints.", "responses": { "200": { "description": "API documentation" } } } }, "/api/openapi.json": { "get": { "summary": "OpenAPI 规范", "description": "OpenAPI 3.0 specification for all endpoints.", "responses": { "200": { "description": "OpenAPI 3.0 spec" } } } }, "/api/batch": { "post": { "summary": "批量查询", "description": "Batch GPU query (max 10 GPUs).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "gpus": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "profile": { "type": "string", "default": "general" }, "limit": { "type": "integer", "default": 3, "maximum": 10 } }, "required": [ "gpus" ] } } } }, "responses": { "200": { "description": "Batch query results" } } } }, "/api/seed": { "post": { "summary": "数据灌入（管理）", "description": "Seed data from KV to D1.", "responses": { "200": { "description": "Seed result" } } } }, "/api/cron/enrich": { "get": { "summary": "定时模型同步", "description": "Cron: enrich models from HuggingFace.", "parameters": [ { "name": "trigger", "in": "query", "schema": { "type": "string" }, "description": "CRON secret" } ], "responses": { "200": { "description": "Enrich result" } } } }, "/api/cron/snapshot": { "post": { "summary": "定时快照（管理）", "description": "Take daily snapshot for trends.", "responses": { "200": { "description": "Snapshot result" } } } } } }