kiku-agent 1.3.2 → 1.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/README.md +69 -12
  2. package/package.json +2 -1
  3. package/server/agent/agentCore.js +319 -46
  4. package/server/agent/appPaths.js +31 -0
  5. package/server/agent/audioPlayer.js +339 -12
  6. package/server/agent/autoContext.js +193 -0
  7. package/server/agent/catalogEntityResolver.js +170 -28
  8. package/server/agent/clarifyingQuestions.js +137 -35
  9. package/server/agent/cli.js +177 -48
  10. package/server/agent/cloudAdapters.js +116 -0
  11. package/server/agent/commandRegistry.js +409 -80
  12. package/server/agent/commands.js +1056 -125
  13. package/server/agent/config.js +1088 -690
  14. package/server/agent/contextCompactor.js +213 -21
  15. package/server/agent/cpuMetrics.js +199 -0
  16. package/server/agent/engineService.js +591 -0
  17. package/server/agent/eval/modules/evaluation/runner.js +4 -14
  18. package/server/agent/eval/modules/evaluation/scoring.js +15 -3
  19. package/server/agent/eval/modules/server/evalApi.js +5 -5
  20. package/server/agent/eval/modules/ui/evalUi.js +7 -4
  21. package/server/agent/eventBus.js +1 -0
  22. package/server/agent/ink/main.jsx +196 -191
  23. package/server/agent/jobManager.js +11 -1
  24. package/server/agent/lanDiscovery.js +721 -23
  25. package/server/agent/llmClient.js +317 -71
  26. package/server/agent/lmStudioWakeup.js +517 -65
  27. package/server/agent/locationService.js +797 -0
  28. package/server/agent/mcpQuizData.js +509 -0
  29. package/server/agent/memory/contextAllocator.js +19 -7
  30. package/server/agent/memory.js +3 -1
  31. package/server/agent/modelCompatibility.js +352 -0
  32. package/server/agent/modelDefaults.js +1 -0
  33. package/server/agent/modelManager.js +46 -2
  34. package/server/agent/newsWatch.js +9 -3
  35. package/server/agent/processManager.js +229 -0
  36. package/server/agent/prompts.js +174 -8
  37. package/server/agent/routingInterceptor.js +9 -1
  38. package/server/agent/sanitizer.js +41 -6
  39. package/server/agent/searchQueryPlanner.js +202 -0
  40. package/server/agent/session.js +59 -4
  41. package/server/agent/tests/agentFollowUps.test.js +128 -2
  42. package/server/agent/tests/agentMusicControl.test.js +245 -0
  43. package/server/agent/tests/apiRouter.test.js +1 -1
  44. package/server/agent/tests/autoContext.test.js +176 -0
  45. package/server/agent/tests/bilibiliEmbed.test.js +45 -0
  46. package/server/agent/tests/chatHardening.test.js +121 -0
  47. package/server/agent/tests/chineseWebSearchEscalation.test.js +62 -0
  48. package/server/agent/tests/clarifyingQuestions.test.js +33 -0
  49. package/server/agent/tests/cliAutomation.test.js +38 -1
  50. package/server/agent/tests/cloudProviders.test.js +91 -3
  51. package/server/agent/tests/commands.test.js +92 -3
  52. package/server/agent/tests/contextIntelligence.test.js +50 -3
  53. package/server/agent/tests/cpuMetrics.test.js +101 -0
  54. package/server/agent/tests/decisionAndSearchEnhancements.test.js +32 -0
  55. package/server/agent/tests/edgeCasesScenarios.test.js +82 -0
  56. package/server/agent/tests/engineService.test.js +436 -0
  57. package/server/agent/tests/engineUnload.test.js +94 -0
  58. package/server/agent/tests/envCommand.test.js +69 -0
  59. package/server/agent/tests/evalMetrics.test.js +8 -0
  60. package/server/agent/tests/fetchApi.test.js +99 -0
  61. package/server/agent/tests/hybridWebSearch.test.js +2 -0
  62. package/server/agent/tests/lanDiscovery.test.js +5 -0
  63. package/server/agent/tests/lanInterfaces.test.js +510 -0
  64. package/server/agent/tests/lmStudioWakeup.test.js +278 -0
  65. package/server/agent/tests/locationTool.test.js +278 -0
  66. package/server/agent/tests/memoryRoute.test.js +173 -0
  67. package/server/agent/tests/memoryUiNormalization.test.js +75 -0
  68. package/server/agent/tests/modelCompatibility.test.js +148 -0
  69. package/server/agent/tests/modelManager.test.js +32 -0
  70. package/server/agent/tests/musicControlUiBridge.test.js +113 -0
  71. package/server/agent/tests/nextGenArchitecture.test.js +4 -2
  72. package/server/agent/tests/openDomainPrompt.test.js +197 -0
  73. package/server/agent/tests/openDomainSearch.test.js +121 -0
  74. package/server/agent/tests/processManager.test.js +144 -0
  75. package/server/agent/tests/providerPersistence.test.js +10 -5
  76. package/server/agent/tests/quickActionsAndModals.test.js +180 -0
  77. package/server/agent/tests/searchQueryPlanner.test.js +108 -0
  78. package/server/agent/tests/securityAuditRemediation.test.js +16 -9
  79. package/server/agent/tests/securityAuditRemediations2.test.js +154 -0
  80. package/server/agent/tests/securityHardening.test.js +4 -4
  81. package/server/agent/tests/sessionAndCopy.test.js +39 -4
  82. package/server/agent/tests/sidebarControls.test.js +34 -0
  83. package/server/agent/tests/statefulMemory.test.js +8 -1
  84. package/server/agent/tests/textProtocolLoop.test.js +71 -0
  85. package/server/agent/tests/textToolParsing.test.js +48 -0
  86. package/server/agent/tests/toolRoutingRegressions.test.js +41 -0
  87. package/server/agent/tests/unifiedEndpoints.test.js +13 -6
  88. package/server/agent/tests/v110Features.test.js +1 -1
  89. package/server/agent/tests/vramEstimator.test.js +75 -0
  90. package/server/agent/tests/webChatDocs.test.js +199 -0
  91. package/server/agent/tests/webChatInferenceControl.test.js +298 -0
  92. package/server/agent/tests/webChatInspection.test.js +256 -5
  93. package/server/agent/tests/webChatMcp.test.js +94 -0
  94. package/server/agent/tests/webExtract.test.js +23 -0
  95. package/server/agent/tests/webSources.test.js +46 -12
  96. package/server/agent/textToolProtocol.js +173 -46
  97. package/server/agent/toolRouter.js +318 -44
  98. package/server/agent/tools.js +877 -96
  99. package/server/agent/ui.js +39 -34
  100. package/server/agent/vramService.js +35 -54
  101. package/server/agent/webSearch.js +441 -162
  102. package/server/agent/websearch/orchestrator.js +15 -5
  103. package/server/agent/websearch/resilience/cache.js +9 -2
  104. package/server/agent/websearch/security/ssrf.js +41 -10
  105. package/server/agent/youtubeAuth.js +5 -20
  106. package/server/apiRouter.js +5558 -4422
  107. package/server/mcp/data/discography.js +2 -2
  108. package/server/mcp/examples/antigravity.example.json +17 -0
  109. package/server/mcp/handler.js +8 -4
  110. package/server/mcp/security.js +220 -21
  111. package/server/mcp/server.js +2 -1
  112. package/server/mcp/tests/connection.test.js +14 -8
  113. package/server/mcp/tests/mcpKeyAuth.test.js +156 -0
  114. package/server/mcp/tools.js +7 -1
  115. package/server/supabase_migration_prefix.sql +102 -0
  116. package/server/supabase_schema.sql +18 -18
  117. package/server/web-chat/core/connection.js +179 -218
  118. package/server/web-chat/core/conversationContext.js +9 -2
  119. package/server/web-chat/core/directCatalogEngine.js +52 -28
  120. package/server/web-chat/core/dramaKnowledge.js +33 -22
  121. package/server/web-chat/core/followUpEngine.js +735 -81
  122. package/server/web-chat/core/futureEventGuard.js +5 -1
  123. package/server/web-chat/core/musicControlAction.js +70 -0
  124. package/server/web-chat/core/security.js +32 -21
  125. package/server/web-chat/core/toolInspector.js +6 -6
  126. package/server/web-chat/core/urlGuard.js +45 -0
  127. package/server/web-chat/router.js +204 -157
  128. package/server/web-chat/routes/chatRoute.js +885 -488
  129. package/server/web-chat/routes/engineRoute.js +270 -0
  130. package/server/web-chat/routes/exportRoute.js +1 -1
  131. package/server/web-chat/routes/lanDiscoveryRoute.js +17 -2
  132. package/server/web-chat/routes/lmStudioLoadRoute.js +172 -0
  133. package/server/web-chat/routes/mcpRoute.js +386 -0
  134. package/server/web-chat/routes/memoryRoute.js +253 -0
  135. package/server/web-chat/routes/providerRoute.js +49 -16
  136. package/server/web-chat/routes/staticRoute.js +306 -17
  137. package/server/web-chat/routes/statusRoute.js +194 -73
  138. package/server/web-chat/routes/suggestRoute.js +11 -3
  139. package/server/web-chat/routes/verifyRoute.js +26 -4
  140. package/server/web-chat/server.js +7 -6
  141. package/server/web-chat/ui/docsBuilder.js +3558 -0
  142. package/server/web-chat/ui/htmlBuilder.js +12 -0
  143. package/server/web-chat/ui/scripts/client.js +3401 -1302
  144. package/server/web-chat/ui/scripts/webchatI18n.js +155 -153
  145. package/server/web-chat/ui/settingsBuilder.js +7870 -0
  146. package/server/web-chat/ui/styles/lan-card.css +165 -0
  147. package/server/web-chat/ui/styles/main.css +4289 -447
  148. package/server/web-chat/ui/sw.js +64 -0
  149. package/server/web-chat/ui/templates/body.html +407 -281
  150. package/src/data/awardsData.js +146 -146
  151. package/src/data/musicVideoData.js +6 -4
  152. package/src/lib/vram/estimator.js +195 -19
package/server/web-chat/ui/docsBuilder.js ADDED
@@ -0,0 +1,3558 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+
5
+ const __filename = fileURLToPath(import.meta.url);
6
+ const __dirname = path.dirname(__filename);
7
+ const TOKENS_PATH = path.resolve(__dirname, '../../../tokens.css');
8
+
9
+ let cachedTokens = null;
10
+
11
+ function getTokensCss() {
12
+ if (process.env.NODE_ENV === 'production' && cachedTokens) {
13
+ return cachedTokens;
14
+ }
15
+ try {
16
+ if (fs.existsSync(TOKENS_PATH)) {
17
+ cachedTokens = fs.readFileSync(TOKENS_PATH, 'utf8');
18
+ return cachedTokens;
19
+ }
20
+ } catch {}
21
+ return '';
22
+ }
23
+
24
+ export function getDocsHtml() {
25
+ const tokens = getTokensCss();
26
+
27
+ return `<!DOCTYPE html>
28
+ <html lang="th" data-theme="dark" class="scroll-smooth">
29
+ <head>
30
+ <meta charset="UTF-8">
31
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
32
+ <title>Inference Control Center — Architecture &amp; System Manual</title>
33
+ <link rel="icon" href="/favicon.ico" />
34
+ <link rel="preconnect" href="https://fonts.googleapis.com">
35
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
36
+ <link rel="preload" href="/fonts/GoogleSans-Latin-400.woff2" as="font" type="font/woff2" crossorigin>
37
+ <link rel="preload" href="/fonts/GoogleSans-Thai-400.woff2" as="font" type="font/woff2" crossorigin>
38
+ <link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600;700&family=Noto+Sans+SC:wght@300;400;500;600;700;900&display=swap" rel="stylesheet">
39
+ <link rel="stylesheet" href="/fonts/google-sans-official.css">
40
+ <style>
41
+ ${tokens}
42
+
43
+ :root {
44
+ --bg-deep: #07090e;
45
+ --bg-surface: #0e131f;
46
+ --bg-panel: rgba(17, 24, 39, 0.72);
47
+ --bg-panel-hover: rgba(30, 41, 59, 0.82);
48
+ --border-subtle: rgba(255, 255, 255, 0.08);
49
+ --border-focus: rgba(244, 114, 182, 0.45);
50
+ --primary-glow: rgba(244, 114, 182, 0.18);
51
+ --accent-pink: #f472b6;
52
+ --accent-rose: #fb7185;
53
+ --accent-purple: #a855f7;
54
+ --accent-cyan: #38bdf8;
55
+ --accent-emerald: #34d399;
56
+ --accent-amber: #fbbf24;
57
+ --accent-red: #f87171;
58
+ --text-main: #f1f5f9;
59
+ --text-muted: #94a3b8;
60
+ --text-subtle: #64748b;
61
+ --code-bg: rgba(11, 15, 25, 0.85);
62
+ --sidebar-w: 280px;
63
+ }
64
+
65
+ [data-theme="light"] {
66
+ --bg-deep: #f8fafc;
67
+ --bg-surface: #ffffff;
68
+ --bg-panel: rgba(255, 255, 255, 0.9);
69
+ --bg-panel-hover: rgba(241, 245, 249, 0.95);
70
+ --border-subtle: rgba(0, 0, 0, 0.08);
71
+ --border-focus: rgba(219, 39, 119, 0.5);
72
+ --primary-glow: rgba(244, 114, 182, 0.12);
73
+ --accent-pink: #db2777;
74
+ --accent-rose: #e11d48;
75
+ --accent-purple: #9333ea;
76
+ --accent-cyan: #0284c7;
77
+ --accent-emerald: #059669;
78
+ --accent-amber: #b45309;
79
+ --accent-red: #dc2626;
80
+ --text-main: #0f172a;
81
+ --text-muted: #475569;
82
+ --text-subtle: #64748b;
83
+ --code-bg: #0f172a;
84
+ }
85
+
86
+ *, *::before, *::after, html, body, input, button, select {
87
+ box-sizing: border-box;
88
+ font-family: 'Google Sans', 'Google Sans Text', 'Product Sans', 'Noto Sans Thai', 'Noto Sans SC', sans-serif !important;
89
+ -webkit-font-smoothing: antialiased !important;
90
+ -moz-osx-font-smoothing: grayscale !important;
91
+ }
92
+
93
+ body {
94
+ background: var(--bg-deep);
95
+ color: var(--text-main);
96
+ min-height: 100vh;
97
+ display: flex;
98
+ flex-direction: column;
99
+ background-image:
100
+ radial-gradient(circle at 12% 10%, rgba(244, 114, 182, 0.08) 0%, transparent 45%),
101
+ radial-gradient(circle at 88% 85%, rgba(56, 189, 248, 0.07) 0%, transparent 45%);
102
+ background-attachment: fixed;
103
+ margin: 0;
104
+ padding: 0;
105
+ }
106
+
107
+ .top-navbar {
108
+ position: sticky;
109
+ top: 0;
110
+ z-index: 100;
111
+ backdrop-filter: blur(20px);
112
+ -webkit-backdrop-filter: blur(20px);
113
+ background: rgba(11, 15, 25, 0.8);
114
+ border-bottom: 1px solid var(--border-subtle);
115
+ padding: 0 24px;
116
+ height: 64px;
117
+ display: flex;
118
+ align-items: center;
119
+ justify-content: space-between;
120
+ gap: 12px;
121
+ }
122
+
123
+ [data-theme="light"] .top-navbar {
124
+ background: rgba(255, 255, 255, 0.88);
125
+ }
126
+
127
+ .navbar-left {
128
+ display: flex;
129
+ align-items: center;
130
+ gap: 12px;
131
+ flex: 1;
132
+ min-width: 0;
133
+ }
134
+
135
+ .nav-btn {
136
+ display: inline-flex;
137
+ align-items: center;
138
+ gap: 8px;
139
+ padding: 7px 14px;
140
+ border-radius: 9999px;
141
+ background: var(--bg-panel);
142
+ border: 1px solid var(--border-subtle);
143
+ color: var(--text-main);
144
+ font-size: 13px;
145
+ font-weight: 600;
146
+ text-decoration: none;
147
+ white-space: nowrap;
148
+ transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1);
149
+ }
150
+
151
+ .nav-btn:hover {
152
+ background: var(--bg-panel-hover);
153
+ border-color: var(--accent-pink);
154
+ color: var(--accent-pink);
155
+ transform: translateY(-1px);
156
+ }
157
+
158
+ .brand-kicker {
159
+ font-weight: 800;
160
+ letter-spacing: 0.06em;
161
+ background: linear-gradient(135deg, #f472b6, #fb7185);
162
+ -webkit-background-clip: text;
163
+ -webkit-text-fill-color: transparent;
164
+ padding: 2px 0;
165
+ white-space: nowrap;
166
+ font-size: 13.5px;
167
+ }
168
+
169
+ .navbar-right {
170
+ display: flex;
171
+ align-items: center;
172
+ gap: 10px;
173
+ }
174
+
175
+ .btn-icon-nav {
176
+ width: 36px;
177
+ height: 36px;
178
+ border-radius: 10px;
179
+ border: 1px solid var(--border-subtle);
180
+ background: var(--bg-panel);
181
+ color: var(--text-muted);
182
+ cursor: pointer;
183
+ display: flex;
184
+ align-items: center;
185
+ justify-content: center;
186
+ font-size: 12.5px;
187
+ font-weight: 700;
188
+ transition: all 0.2s;
189
+ }
190
+
191
+ .btn-icon-nav:hover {
192
+ background: var(--bg-panel-hover);
193
+ color: var(--text-main);
194
+ border-color: var(--border-focus);
195
+ }
196
+
197
+ /* Layout */
198
+ .docs-layout {
199
+ display: flex;
200
+ max-width: 1440px;
201
+ width: 100%;
202
+ margin: 0 auto;
203
+ padding: 32px 24px 64px;
204
+ gap: 32px;
205
+ box-sizing: border-box;
206
+ flex: 1;
207
+ }
208
+
209
+ /* Sidebar */
210
+ .docs-sidebar {
211
+ width: var(--sidebar-w);
212
+ flex-shrink: 0;
213
+ position: sticky;
214
+ top: 96px;
215
+ height: fit-content;
216
+ max-height: calc(100vh - 120px);
217
+ overflow-y: auto;
218
+ padding-right: 8px;
219
+ }
220
+
221
+ .docs-sidebar::-webkit-scrollbar {
222
+ width: 4px;
223
+ }
224
+ .docs-sidebar::-webkit-scrollbar-thumb {
225
+ background: var(--border-subtle);
226
+ border-radius: 4px;
227
+ }
228
+
229
+ .sidebar-heading {
230
+ font-size: 11px;
231
+ font-weight: 700;
232
+ letter-spacing: 0.08em;
233
+ text-transform: uppercase;
234
+ color: var(--text-subtle);
235
+ margin-bottom: 12px;
236
+ padding-left: 12px;
237
+ }
238
+
239
+ .sidebar-menu {
240
+ display: flex;
241
+ flex-direction: column;
242
+ gap: 4px;
243
+ list-style: none;
244
+ padding: 0;
245
+ margin: 0;
246
+ }
247
+
248
+ .sidebar-link {
249
+ display: flex;
250
+ align-items: center;
251
+ gap: 10px;
252
+ padding: 9px 14px;
253
+ border-radius: 10px;
254
+ color: var(--text-muted);
255
+ text-decoration: none;
256
+ font-size: 13px;
257
+ font-weight: 500;
258
+ transition: all 0.18s ease;
259
+ border: 1px solid transparent;
260
+ }
261
+
262
+ .sidebar-link:hover {
263
+ color: var(--text-main);
264
+ background: rgba(255, 255, 255, 0.04);
265
+ border-color: var(--border-subtle);
266
+ }
267
+
268
+ .sidebar-link.active {
269
+ color: var(--accent-pink);
270
+ background: rgba(244, 114, 182, 0.1);
271
+ border-color: rgba(244, 114, 182, 0.25);
272
+ font-weight: 600;
273
+ }
274
+
275
+ .sidebar-link svg {
276
+ flex-shrink: 0;
277
+ }
278
+
279
+ /* Sub-Navigation in Sidebar */
280
+ .sidebar-sublist {
281
+ list-style: none;
282
+ padding: 3px 0 6px 26px;
283
+ margin: 0;
284
+ display: flex;
285
+ flex-direction: column;
286
+ gap: 2px;
287
+ border-left: 1px dashed var(--border-subtle);
288
+ margin-left: 18px;
289
+ }
290
+
291
+ .sidebar-sublink {
292
+ display: flex;
293
+ align-items: center;
294
+ gap: 7px;
295
+ padding: 4px 8px;
296
+ font-size: 11.5px;
297
+ color: var(--text-subtle);
298
+ text-decoration: none;
299
+ border-radius: 6px;
300
+ transition: all 0.15s ease;
301
+ white-space: nowrap;
302
+ overflow: hidden;
303
+ text-overflow: ellipsis;
304
+ }
305
+
306
+ .sidebar-sublink::before {
307
+ content: '';
308
+ width: 4px;
309
+ height: 4px;
310
+ border-radius: 50%;
311
+ background: var(--text-subtle);
312
+ opacity: 0.6;
313
+ flex-shrink: 0;
314
+ transition: all 0.15s;
315
+ }
316
+
317
+ .sidebar-sublink:hover {
318
+ color: var(--text-main);
319
+ background: rgba(255, 255, 255, 0.04);
320
+ }
321
+
322
+ .sidebar-sublink:hover::before {
323
+ background: var(--accent-pink);
324
+ opacity: 1;
325
+ transform: scale(1.4);
326
+ }
327
+
328
+ .sidebar-sublink.active {
329
+ color: var(--accent-cyan);
330
+ font-weight: 600;
331
+ }
332
+
333
+ .sidebar-sublink.active::before {
334
+ background: var(--accent-cyan);
335
+ opacity: 1;
336
+ transform: scale(1.5);
337
+ }
338
+
339
+ /* Sub-section Headings */
340
+ .sub-section {
341
+ margin-top: 28px;
342
+ padding-top: 20px;
343
+ border-top: 1px solid var(--border-subtle);
344
+ scroll-margin-top: 100px;
345
+ }
346
+
347
+ .sub-title {
348
+ font-size: 16px;
349
+ font-weight: 700;
350
+ color: var(--text-main);
351
+ display: flex;
352
+ align-items: center;
353
+ gap: 8px;
354
+ margin: 0 0 10px;
355
+ }
356
+
357
+ .sub-title svg {
358
+ color: var(--accent-pink);
359
+ flex-shrink: 0;
360
+ }
361
+
362
+ /* Parameter Grid & Interactive Cards */
363
+ .param-grid {
364
+ display: grid;
365
+ grid-template-columns: repeat(auto-fit, minmax(310px, 1fr));
366
+ gap: 16px;
367
+ margin: 18px 0;
368
+ }
369
+
370
+ .param-card {
371
+ background: rgba(255, 255, 255, 0.025);
372
+ border: 1px solid var(--border-subtle);
373
+ border-radius: 14px;
374
+ padding: 16px;
375
+ display: flex;
376
+ flex-direction: column;
377
+ gap: 10px;
378
+ transition: all 0.2s ease;
379
+ position: relative;
380
+ overflow: hidden;
381
+ }
382
+
383
+ .param-card:hover {
384
+ background: rgba(255, 255, 255, 0.045);
385
+ border-color: rgba(244, 114, 182, 0.35);
386
+ box-shadow: 0 6px 20px rgba(0, 0, 0, 0.25);
387
+ transform: translateY(-2px);
388
+ }
389
+
390
+ [data-theme="light"] .param-card {
391
+ background: rgba(255, 255, 255, 0.85);
392
+ box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
393
+ }
394
+
395
+ [data-theme="light"] .param-card:hover {
396
+ border-color: var(--accent-pink);
397
+ box-shadow: 0 8px 24px rgba(244, 114, 182, 0.15);
398
+ }
399
+
400
+ .param-header {
401
+ display: flex;
402
+ align-items: center;
403
+ justify-content: space-between;
404
+ gap: 8px;
405
+ flex-wrap: wrap;
406
+ }
407
+
408
+ .param-name {
409
+ font-family: 'JetBrains Mono', monospace;
410
+ font-size: 13.5px;
411
+ font-weight: 700;
412
+ color: var(--accent-cyan);
413
+ }
414
+
415
+ .param-badges {
416
+ display: flex;
417
+ align-items: center;
418
+ gap: 6px;
419
+ }
420
+
421
+ .badge-type {
422
+ font-family: 'JetBrains Mono', monospace;
423
+ font-size: 10.5px;
424
+ font-weight: 600;
425
+ padding: 2px 7px;
426
+ border-radius: 6px;
427
+ background: rgba(168, 85, 247, 0.12);
428
+ color: #c084fc;
429
+ border: 1px solid rgba(168, 85, 247, 0.25);
430
+ }
431
+
432
+ .badge-impact-high {
433
+ font-size: 10px;
434
+ font-weight: 700;
435
+ padding: 2px 6px;
436
+ border-radius: 6px;
437
+ background: rgba(239, 68, 68, 0.12);
438
+ color: #f87171;
439
+ border: 1px solid rgba(239, 68, 68, 0.25);
440
+ }
441
+
442
+ .badge-impact-med {
443
+ font-size: 10px;
444
+ font-weight: 700;
445
+ padding: 2px 6px;
446
+ border-radius: 6px;
447
+ background: rgba(251, 191, 36, 0.12);
448
+ color: #fbbf24;
449
+ border: 1px solid rgba(251, 191, 36, 0.25);
450
+ }
451
+
452
+ .badge-impact-low {
453
+ font-size: 10px;
454
+ font-weight: 700;
455
+ padding: 2px 6px;
456
+ border-radius: 6px;
457
+ background: rgba(52, 211, 153, 0.12);
458
+ color: #34d399;
459
+ border: 1px solid rgba(52, 211, 153, 0.25);
460
+ }
461
+
462
+ .param-desc {
463
+ font-size: 12.5px;
464
+ line-height: 1.55;
465
+ color: var(--text-muted);
466
+ margin: 0;
467
+ }
468
+
469
+ .param-meta-row {
470
+ display: flex;
471
+ align-items: center;
472
+ justify-content: space-between;
473
+ padding-top: 8px;
474
+ border-top: 1px solid var(--border-subtle);
475
+ font-size: 11px;
476
+ color: var(--text-subtle);
477
+ }
478
+
479
+ .param-meta-val {
480
+ font-family: 'JetBrains Mono', monospace;
481
+ color: var(--text-main);
482
+ font-weight: 600;
483
+ }
484
+
485
+ /* CLI Command Cards */
486
+ .cmd-grid {
487
+ display: flex;
488
+ flex-direction: column;
489
+ gap: 14px;
490
+ margin: 18px 0;
491
+ }
492
+
493
+ .cmd-card {
494
+ background: rgba(255, 255, 255, 0.02);
495
+ border: 1px solid var(--border-subtle);
496
+ border-radius: 12px;
497
+ padding: 14px 16px;
498
+ display: flex;
499
+ flex-direction: column;
500
+ gap: 8px;
501
+ transition: all 0.2s;
502
+ }
503
+
504
+ .cmd-card:hover {
505
+ border-color: rgba(56, 189, 248, 0.35);
506
+ background: rgba(255, 255, 255, 0.035);
507
+ }
508
+
509
+ .cmd-syntax-bar {
510
+ display: flex;
511
+ align-items: center;
512
+ justify-content: space-between;
513
+ gap: 10px;
514
+ flex-wrap: wrap;
515
+ }
516
+
517
+ .cmd-syntax {
518
+ font-family: 'JetBrains Mono', monospace;
519
+ font-size: 13px;
520
+ font-weight: 700;
521
+ color: var(--accent-pink);
522
+ }
523
+
524
+ .cmd-tag {
525
+ font-size: 10px;
526
+ font-weight: 700;
527
+ text-transform: uppercase;
528
+ letter-spacing: 0.05em;
529
+ padding: 2px 7px;
530
+ border-radius: 5px;
531
+ background: rgba(56, 189, 248, 0.1);
532
+ color: var(--accent-cyan);
533
+ border: 1px solid rgba(56, 189, 248, 0.2);
534
+ }
535
+
536
+ .cmd-desc {
537
+ font-size: 12px;
538
+ line-height: 1.5;
539
+ color: var(--text-muted);
540
+ margin: 0;
541
+ }
542
+
543
+ /* Content Area */
544
+ .docs-content {
545
+ flex: 1;
546
+ min-width: 0;
547
+ }
548
+
549
+ .docs-hero {
550
+ margin-bottom: 36px;
551
+ padding-bottom: 24px;
552
+ border-bottom: 1px solid var(--border-subtle);
553
+ }
554
+
555
+ .docs-badge {
556
+ display: inline-flex;
557
+ align-items: center;
558
+ gap: 6px;
559
+ padding: 4px 10px;
560
+ border-radius: 999px;
561
+ background: rgba(244, 114, 182, 0.12);
562
+ border: 1px solid rgba(244, 114, 182, 0.3);
563
+ color: var(--accent-pink);
564
+ font-size: 11px;
565
+ font-weight: 700;
566
+ letter-spacing: 0.05em;
567
+ text-transform: uppercase;
568
+ margin-bottom: 12px;
569
+ }
570
+
571
+ .docs-title {
572
+ font-size: 32px;
573
+ font-weight: 800;
574
+ letter-spacing: -0.02em;
575
+ color: var(--text-main);
576
+ margin: 0 0 10px 0;
577
+ }
578
+
579
+ .docs-subtitle {
580
+ font-size: 15px;
581
+ line-height: 1.6;
582
+ color: var(--text-muted);
583
+ margin: 0;
584
+ max-width: 820px;
585
+ }
586
+
587
+ /* Live Hardware Banner */
588
+ .live-hw-card {
589
+ background: linear-gradient(135deg, rgba(14, 23, 42, 0.85), rgba(15, 23, 42, 0.95));
590
+ border: 1px solid rgba(56, 189, 248, 0.28);
591
+ border-radius: 16px;
592
+ padding: 18px 22px;
593
+ margin-bottom: 36px;
594
+ display: flex;
595
+ align-items: center;
596
+ justify-content: space-between;
597
+ flex-wrap: wrap;
598
+ gap: 16px;
599
+ box-shadow: 0 8px 30px rgba(0, 0, 0, 0.25);
600
+ }
601
+
602
+ [data-theme="light"] .live-hw-card {
603
+ background: linear-gradient(135deg, #ffffff, #f0f9ff);
604
+ border-color: rgba(2, 132, 199, 0.25);
605
+ box-shadow: 0 8px 30px rgba(2, 132, 199, 0.06);
606
+ }
607
+
608
+ .live-hw-info {
609
+ display: flex;
610
+ align-items: center;
611
+ gap: 14px;
612
+ }
613
+
614
+ .live-hw-icon {
615
+ width: 44px;
616
+ height: 44px;
617
+ border-radius: 12px;
618
+ background: rgba(56, 189, 248, 0.12);
619
+ border: 1px solid rgba(56, 189, 248, 0.25);
620
+ color: var(--accent-cyan);
621
+ display: flex;
622
+ align-items: center;
623
+ justify-content: center;
624
+ flex-shrink: 0;
625
+ }
626
+
627
+ .live-hw-title {
628
+ font-size: 14px;
629
+ font-weight: 700;
630
+ color: var(--text-main);
631
+ }
632
+
633
+ .live-hw-meta {
634
+ font-size: 12.5px;
635
+ color: var(--text-muted);
636
+ margin-top: 2px;
637
+ }
638
+
639
+ .live-hw-chips {
640
+ display: flex;
641
+ align-items: center;
642
+ gap: 8px;
643
+ flex-wrap: wrap;
644
+ }
645
+
646
+ .hw-chip {
647
+ padding: 4px 10px;
648
+ border-radius: 6px;
649
+ font-family: 'JetBrains Mono', monospace;
650
+ font-size: 11.5px;
651
+ font-weight: 600;
652
+ background: rgba(255, 255, 255, 0.05);
653
+ border: 1px solid var(--border-subtle);
654
+ color: var(--text-main);
655
+ }
656
+
657
+ /* Section Cards */
658
+ .doc-section {
659
+ background: var(--bg-panel);
660
+ backdrop-filter: blur(24px);
661
+ -webkit-backdrop-filter: blur(24px);
662
+ border: 1px solid var(--border-subtle);
663
+ border-radius: 18px;
664
+ padding: 30px;
665
+ margin-bottom: 36px;
666
+ scroll-margin-top: 90px;
667
+ box-shadow: 0 8px 32px rgba(0, 0, 0, 0.16);
668
+ transition: border-color 0.2s;
669
+ }
670
+
671
+ .doc-section:hover {
672
+ border-color: rgba(255, 255, 255, 0.14);
673
+ }
674
+
675
+ .doc-section-header {
676
+ display: flex;
677
+ align-items: flex-start;
678
+ gap: 14px;
679
+ margin-bottom: 22px;
680
+ padding-bottom: 16px;
681
+ border-bottom: 1px solid var(--border-subtle);
682
+ }
683
+
684
+ .section-icon-badge {
685
+ width: 42px;
686
+ height: 42px;
687
+ border-radius: 12px;
688
+ display: flex;
689
+ align-items: center;
690
+ justify-content: center;
691
+ flex-shrink: 0;
692
+ }
693
+
694
+ .badge-cyan { background: rgba(56, 189, 248, 0.1); color: var(--accent-cyan); border: 1px solid rgba(56, 189, 248, 0.25); }
695
+ .badge-pink { background: rgba(244, 114, 182, 0.1); color: var(--accent-pink); border: 1px solid rgba(244, 114, 182, 0.25); }
696
+ .badge-emerald { background: rgba(52, 211, 153, 0.1); color: var(--accent-emerald); border: 1px solid rgba(52, 211, 153, 0.25); }
697
+ .badge-amber { background: rgba(251, 191, 36, 0.1); color: var(--accent-amber); border: 1px solid rgba(251, 191, 36, 0.25); }
698
+ .badge-purple { background: rgba(168, 85, 247, 0.1); color: var(--accent-purple); border: 1px solid rgba(168, 85, 247, 0.25); }
699
+
700
+ .doc-section-title {
701
+ font-size: 20px;
702
+ font-weight: 800;
703
+ letter-spacing: -0.01em;
704
+ color: var(--text-main);
705
+ margin: 0;
706
+ }
707
+
708
+ .doc-section-desc {
709
+ font-size: 13px;
710
+ color: var(--text-muted);
711
+ margin: 4px 0 0;
712
+ line-height: 1.5;
713
+ }
714
+
715
+ .doc-p {
716
+ font-size: 14px;
717
+ line-height: 1.65;
718
+ color: var(--text-muted);
719
+ margin: 0 0 16px;
720
+ }
721
+
722
+ .doc-p strong {
723
+ color: var(--text-main);
724
+ }
725
+
726
+ /* Comparison Table */
727
+ .table-container {
728
+ width: 100%;
729
+ overflow-x: auto;
730
+ margin: 20px 0;
731
+ border: 1px solid var(--border-subtle);
732
+ border-radius: 12px;
733
+ }
734
+
735
+ .doc-table {
736
+ width: 100%;
737
+ border-collapse: collapse;
738
+ font-size: 13px;
739
+ text-align: left;
740
+ }
741
+
742
+ .doc-table th {
743
+ background: rgba(255, 255, 255, 0.03);
744
+ color: var(--text-main);
745
+ font-weight: 700;
746
+ padding: 12px 16px;
747
+ border-bottom: 1px solid var(--border-subtle);
748
+ white-space: nowrap;
749
+ }
750
+
751
+ .doc-table td {
752
+ padding: 12px 16px;
753
+ border-bottom: 1px solid var(--border-subtle);
754
+ color: var(--text-muted);
755
+ line-height: 1.45;
756
+ }
757
+
758
+ .doc-table tr:last-child td {
759
+ border-bottom: none;
760
+ }
761
+
762
+ .doc-table tr:hover td {
763
+ background: rgba(255, 255, 255, 0.015);
764
+ }
765
+
766
+ /* Callout Card */
767
+ .doc-callout {
768
+ border-radius: 12px;
769
+ padding: 16px 18px;
770
+ margin: 18px 0;
771
+ display: flex;
772
+ gap: 14px;
773
+ font-size: 13px;
774
+ line-height: 1.55;
775
+ }
776
+
777
+ .callout-info {
778
+ background: rgba(56, 189, 248, 0.08);
779
+ border: 1px solid rgba(56, 189, 248, 0.25);
780
+ color: var(--text-main);
781
+ }
782
+
783
+ .callout-tip {
784
+ background: rgba(52, 211, 153, 0.08);
785
+ border: 1px solid rgba(52, 211, 153, 0.25);
786
+ color: var(--text-main);
787
+ }
788
+
789
+ .callout-warn {
790
+ background: rgba(251, 191, 36, 0.08);
791
+ border: 1px solid rgba(251, 191, 36, 0.25);
792
+ color: var(--text-main);
793
+ }
794
+
795
+ .callout-icon {
796
+ flex-shrink: 0;
797
+ margin-top: 2px;
798
+ }
799
+
800
+ /* Code Block */
801
+ .code-block {
802
+ background: var(--code-bg);
803
+ border: 1px solid var(--border-subtle);
804
+ border-radius: 12px;
805
+ margin: 16px 0;
806
+ overflow: hidden;
807
+ position: relative;
808
+ }
809
+
810
+ .code-header {
811
+ display: flex;
812
+ align-items: center;
813
+ justify-content: space-between;
814
+ padding: 8px 14px;
815
+ background: rgba(255, 255, 255, 0.03);
816
+ border-bottom: 1px solid var(--border-subtle);
817
+ font-family: 'JetBrains Mono', monospace;
818
+ font-size: 11.5px;
819
+ color: var(--text-subtle);
820
+ }
821
+
822
+ .btn-copy {
823
+ display: inline-flex;
824
+ align-items: center;
825
+ gap: 4px;
826
+ background: transparent;
827
+ border: 1px solid var(--border-subtle);
828
+ border-radius: 6px;
829
+ padding: 3px 8px;
830
+ color: var(--text-muted);
831
+ font-size: 11px;
832
+ cursor: pointer;
833
+ transition: all 0.2s;
834
+ }
835
+
836
+ .btn-copy:hover {
837
+ background: rgba(255, 255, 255, 0.08);
838
+ color: var(--text-main);
839
+ }
840
+
841
+ .code-block pre {
842
+ margin: 0;
843
+ padding: 14px 16px;
844
+ overflow-x: auto;
845
+ font-family: 'JetBrains Mono', monospace;
846
+ font-size: 12.5px;
847
+ line-height: 1.55;
848
+ color: #e2e8f0;
849
+ }
850
+
851
+ /* Formula Box */
852
+ .formula-card {
853
+ background: rgba(168, 85, 247, 0.06);
854
+ border: 1px solid rgba(168, 85, 247, 0.25);
855
+ border-radius: 14px;
856
+ padding: 16px 20px;
857
+ margin: 18px 0;
858
+ text-align: center;
859
+ }
860
+
861
+ .formula-math {
862
+ font-family: 'JetBrains Mono', monospace;
863
+ font-size: 15px;
864
+ font-weight: 700;
865
+ color: #c084fc;
866
+ letter-spacing: 0.02em;
867
+ }
868
+
869
+ .formula-sub {
870
+ font-size: 12px;
871
+ color: var(--text-muted);
872
+ margin-top: 6px;
873
+ }
874
+
875
+ /* Architecture Visual Diagram */
876
+ .arch-diagram-wrap {
877
+ background: rgba(0, 0, 0, 0.25);
878
+ border: 1px solid var(--border-subtle);
879
+ border-radius: 14px;
880
+ padding: 24px;
881
+ margin: 20px 0;
882
+ display: flex;
883
+ flex-direction: column;
884
+ gap: 16px;
885
+ }
886
+
887
+ .arch-level {
888
+ display: grid;
889
+ grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
890
+ gap: 14px;
891
+ }
892
+
893
+ .arch-node {
894
+ background: rgba(255, 255, 255, 0.03);
895
+ border: 1px solid var(--border-subtle);
896
+ border-radius: 10px;
897
+ padding: 14px 16px;
898
+ position: relative;
899
+ }
900
+
901
+ .arch-node-title {
902
+ font-size: 13.5px;
903
+ font-weight: 700;
904
+ color: var(--text-main);
905
+ display: flex;
906
+ align-items: center;
907
+ gap: 8px;
908
+ }
909
+
910
+ .arch-node-desc {
911
+ font-size: 11.5px;
912
+ color: var(--text-muted);
913
+ margin-top: 4px;
914
+ line-height: 1.4;
915
+ }
916
+
917
+ .arch-arrow {
918
+ text-align: center;
919
+ color: var(--accent-pink);
920
+ font-weight: 700;
921
+ font-size: 14px;
922
+ display: flex;
923
+ align-items: center;
924
+ justify-content: center;
925
+ gap: 6px;
926
+ }
927
+
928
+ /* Floating Back to Top Button */
929
+ .btn-scroll-top {
930
+ position: fixed;
931
+ bottom: 24px;
932
+ right: 20px;
933
+ width: 44px;
934
+ height: 44px;
935
+ border-radius: 50%;
936
+ background: rgba(17, 24, 39, 0.85);
937
+ backdrop-filter: blur(12px);
938
+ -webkit-backdrop-filter: blur(12px);
939
+ border: 1px solid var(--border-subtle);
940
+ color: var(--text-main);
941
+ display: flex;
942
+ align-items: center;
943
+ justify-content: center;
944
+ cursor: pointer;
945
+ box-shadow: 0 6px 24px rgba(0, 0, 0, 0.35);
946
+ opacity: 0;
947
+ transform: translateY(20px) scale(0.9);
948
+ pointer-events: none;
949
+ transition: all 0.25s cubic-bezier(0.16, 1, 0.3, 1);
950
+ z-index: 150;
951
+ touch-action: manipulation;
952
+ }
953
+
954
+ .btn-scroll-top.visible {
955
+ opacity: 1;
956
+ transform: translateY(0) scale(1);
957
+ pointer-events: auto;
958
+ }
959
+
960
+ .btn-scroll-top:active {
961
+ transform: scale(0.92);
962
+ }
963
+
964
+ [data-theme="light"] .btn-scroll-top {
965
+ background: rgba(255, 255, 255, 0.9);
966
+ box-shadow: 0 6px 24px rgba(15, 23, 42, 0.15);
967
+ }
968
+
969
+ /* Mobile & Responsive Enhancements */
970
+ @media (max-width: 960px) {
971
+ .top-navbar {
972
+ height: 56px;
973
+ padding: 0 14px;
974
+ }
975
+
976
+ .brand-kicker {
977
+ display: none;
978
+ }
979
+
980
+ .docs-layout {
981
+ flex-direction: column;
982
+ padding: 0 14px calc(54px + env(safe-area-inset-bottom, 0px));
983
+ gap: 14px;
984
+ }
985
+
986
+ .docs-sidebar {
987
+ width: calc(100% + 28px);
988
+ margin: 0 -14px 10px -14px;
989
+ position: sticky;
990
+ top: 56px;
991
+ z-index: 80;
992
+ backdrop-filter: blur(20px);
993
+ -webkit-backdrop-filter: blur(20px);
994
+ background: rgba(7, 9, 14, 0.88);
995
+ border-bottom: 1px solid var(--border-subtle);
996
+ padding: 8px 14px;
997
+ max-height: none;
998
+ overflow: hidden;
999
+ }
1000
+
1001
+ [data-theme="light"] .docs-sidebar {
1002
+ background: rgba(255, 255, 255, 0.92);
1003
+ }
1004
+
1005
+ .sidebar-heading {
1006
+ display: none;
1007
+ }
1008
+
1009
+ .sidebar-sublist {
1010
+ display: none !important;
1011
+ }
1012
+
1013
+ .param-grid {
1014
+ grid-template-columns: 1fr;
1015
+ }
1016
+
1017
+ .sidebar-menu {
1018
+ flex-direction: row;
1019
+ overflow-x: auto;
1020
+ white-space: nowrap;
1021
+ gap: 6px;
1022
+ padding: 2px 0 4px;
1023
+ scrollbar-width: none;
1024
+ -webkit-overflow-scrolling: touch;
1025
+ scroll-snap-type: x proximity;
1026
+ }
1027
+
1028
+ .sidebar-menu::-webkit-scrollbar {
1029
+ display: none;
1030
+ }
1031
+
1032
+ .sidebar-link {
1033
+ padding: 7px 13px;
1034
+ font-size: 12px;
1035
+ border-radius: 9999px;
1036
+ background: rgba(255, 255, 255, 0.04);
1037
+ border: 1px solid var(--border-subtle);
1038
+ flex-shrink: 0;
1039
+ scroll-snap-align: center;
1040
+ min-height: 36px;
1041
+ touch-action: manipulation;
1042
+ }
1043
+
1044
+ .sidebar-link.active {
1045
+ background: rgba(244, 114, 182, 0.15);
1046
+ border-color: var(--accent-pink);
1047
+ color: var(--accent-pink);
1048
+ }
1049
+
1050
+ .doc-section {
1051
+ padding: 18px 14px;
1052
+ margin-bottom: 18px;
1053
+ border-radius: 14px;
1054
+ scroll-margin-top: 114px;
1055
+ }
1056
+
1057
+ .docs-hero {
1058
+ margin-bottom: 18px;
1059
+ padding-bottom: 14px;
1060
+ }
1061
+
1062
+ .docs-title {
1063
+ font-size: 22px;
1064
+ line-height: 1.25;
1065
+ }
1066
+
1067
+ .docs-subtitle {
1068
+ font-size: 13px;
1069
+ line-height: 1.55;
1070
+ }
1071
+
1072
+ .live-hw-card {
1073
+ flex-direction: column;
1074
+ align-items: stretch;
1075
+ padding: 14px;
1076
+ margin-bottom: 18px;
1077
+ gap: 12px;
1078
+ border-radius: 14px;
1079
+ }
1080
+
1081
+ .live-hw-info {
1082
+ gap: 10px;
1083
+ }
1084
+
1085
+ .live-hw-icon {
1086
+ width: 36px;
1087
+ height: 36px;
1088
+ }
1089
+
1090
+ .live-hw-title {
1091
+ font-size: 13.5px;
1092
+ }
1093
+
1094
+ .live-hw-meta {
1095
+ font-size: 11.5px;
1096
+ }
1097
+
1098
+ .live-hw-chips {
1099
+ display: grid;
1100
+ grid-template-columns: repeat(2, 1fr);
1101
+ gap: 6px;
1102
+ width: 100%;
1103
+ }
1104
+
1105
+ .hw-chip {
1106
+ font-size: 11px;
1107
+ padding: 6px 8px;
1108
+ text-align: center;
1109
+ white-space: nowrap;
1110
+ overflow: hidden;
1111
+ text-overflow: ellipsis;
1112
+ }
1113
+
1114
+ .doc-section-header {
1115
+ gap: 10px;
1116
+ margin-bottom: 14px;
1117
+ padding-bottom: 12px;
1118
+ }
1119
+
1120
+ .section-icon-badge {
1121
+ width: 36px;
1122
+ height: 36px;
1123
+ border-radius: 10px;
1124
+ }
1125
+
1126
+ .doc-section-title {
1127
+ font-size: 17px;
1128
+ }
1129
+
1130
+ .doc-section-desc {
1131
+ font-size: 12px;
1132
+ }
1133
+
1134
+ .doc-p {
1135
+ font-size: 13.5px;
1136
+ line-height: 1.6;
1137
+ margin-bottom: 14px;
1138
+ }
1139
+
1140
+ .formula-card {
1141
+ padding: 14px 10px;
1142
+ margin: 14px 0;
1143
+ border-radius: 12px;
1144
+ }
1145
+
1146
+ .formula-math {
1147
+ font-size: 12px;
1148
+ overflow-x: auto;
1149
+ white-space: nowrap;
1150
+ -webkit-overflow-scrolling: touch;
1151
+ padding: 4px 0;
1152
+ }
1153
+
1154
+ .formula-sub {
1155
+ font-size: 11px;
1156
+ }
1157
+
1158
+ .arch-diagram-wrap {
1159
+ padding: 14px 12px;
1160
+ gap: 10px;
1161
+ margin: 14px 0;
1162
+ border-radius: 12px;
1163
+ }
1164
+
1165
+ .arch-level {
1166
+ grid-template-columns: 1fr;
1167
+ gap: 8px;
1168
+ }
1169
+
1170
+ .arch-node {
1171
+ padding: 10px 12px;
1172
+ }
1173
+
1174
+ .arch-node-title {
1175
+ font-size: 12.5px;
1176
+ }
1177
+
1178
+ .arch-node-desc {
1179
+ font-size: 11px;
1180
+ }
1181
+
1182
+ .arch-arrow {
1183
+ font-size: 12px;
1184
+ padding: 2px 0;
1185
+ }
1186
+
1187
+ .doc-callout {
1188
+ padding: 12px;
1189
+ margin: 14px 0;
1190
+ gap: 10px;
1191
+ font-size: 12.5px;
1192
+ border-radius: 10px;
1193
+ }
1194
+
1195
+ .code-block {
1196
+ margin: 14px 0;
1197
+ border-radius: 10px;
1198
+ }
1199
+
1200
+ .code-header {
1201
+ padding: 6px 12px;
1202
+ font-size: 11px;
1203
+ }
1204
+
1205
+ .code-block pre {
1206
+ padding: 10px 12px;
1207
+ font-size: 11px;
1208
+ line-height: 1.5;
1209
+ -webkit-overflow-scrolling: touch;
1210
+ }
1211
+
1212
+ .table-container {
1213
+ margin: 14px 0;
1214
+ border-radius: 10px;
1215
+ -webkit-overflow-scrolling: touch;
1216
+ }
1217
+
1218
+ .doc-table {
1219
+ font-size: 12px;
1220
+ }
1221
+
1222
+ .doc-table th, .doc-table td {
1223
+ padding: 8px 10px;
1224
+ }
1225
+ }
1226
+
1227
+ @media (max-width: 480px) {
1228
+ .top-navbar {
1229
+ height: 52px;
1230
+ padding: 0 10px;
1231
+ }
1232
+
1233
+ .docs-layout {
1234
+ padding: 0 10px calc(50px + env(safe-area-inset-bottom, 0px));
1235
+ }
1236
+
1237
+ .docs-sidebar {
1238
+ width: calc(100% + 20px);
1239
+ margin: 0 -10px 8px -10px;
1240
+ padding: 6px 10px;
1241
+ top: 52px;
1242
+ }
1243
+
1244
+ .nav-btn {
1245
+ padding: 5px 8px;
1246
+ font-size: 11.5px;
1247
+ gap: 5px;
1248
+ }
1249
+
1250
+ .nav-btn svg {
1251
+ width: 13px;
1252
+ height: 13px;
1253
+ }
1254
+
1255
+ .docs-title {
1256
+ font-size: 20px;
1257
+ }
1258
+
1259
+ .live-hw-chips {
1260
+ grid-template-columns: 1fr;
1261
+ }
1262
+
1263
+ .hw-chip {
1264
+ font-size: 10.5px;
1265
+ }
1266
+
1267
+ .btn-scroll-top {
1268
+ bottom: 18px;
1269
+ right: 14px;
1270
+ width: 40px;
1271
+ height: 40px;
1272
+ }
1273
+ }
1274
+ </style>
1275
+ </head>
1276
+ <body>
1277
+
1278
+ <!-- Top Navbar -->
1279
+ <header class="top-navbar">
1280
+ <div class="navbar-left">
1281
+ <a href="/settings" class="nav-btn" title="กลับหน้าควบคุมการประมวลผล">
1282
+ <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m15 18-6-6 6-6"/></svg>
1283
+ <span data-i18n="navBackSettings">Inference Controls</span>
1284
+ </a>
1285
+ <a href="/" class="nav-btn" title="กลับหน้าแชท">
1286
+ <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
1287
+ <span data-i18n="navBackChat">Chat</span>
1288
+ </a>
1289
+ <span class="brand-kicker">KIKU INFERENCE DOCS</span>
1290
+ </div>
1291
+
1292
+ <div class="navbar-right">
1293
+ <button type="button" class="btn-icon-nav" id="btn-lang" onclick="toggleLanguage()" title="Language (TH / 中文 / EN)">TH</button>
1294
+ <button type="button" class="btn-icon-nav" id="btn-theme" onclick="toggleTheme()" title="Toggle Theme">
1295
+ <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>
1296
+ </button>
1297
+ </div>
1298
+ </header>
1299
+
1300
+ <!-- Main Container -->
1301
+ <div class="docs-layout">
1302
+
1303
+ <!-- Sticky Navigation Sidebar -->
1304
+ <aside class="docs-sidebar">
1305
+ <div class="sidebar-heading" data-i18n="tocHeading">สารบัญเนื้อหา (Contents)</div>
1306
+ <ul class="sidebar-menu">
1307
+ <!-- 1. System Architecture -->
1308
+ <li class="sidebar-item">
1309
+ <a href="#section-arch" class="sidebar-link active" onclick="highlightSidebar(this)">
1310
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="12 2 2 7 12 12 22 7 12 2"/><polyline points="2 17 12 22 22 17"/><polyline points="2 12 12 17 22 12"/></svg>
1311
+ <span data-i18n="tocArch">1. สถาปัตยกรรมระบบ</span>
1312
+ </a>
1313
+ <ul class="sidebar-sublist">
1314
+ <li><a href="#arch-topology" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocArch1">1.1 3-Tier Suite Topology</a></li>
1315
+ <li><a href="#arch-ipc" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocArch2">1.2 ReAct Loop &amp; Context</a></li>
1316
+ <li><a href="#arch-persistence" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocArch3">1.3 Atomic Persistence Queue</a></li>
1317
+ </ul>
1318
+ </li>
1319
+
1320
+ <!-- 2. Local Engines -->
1321
+ <li class="sidebar-item">
1322
+ <a href="#section-engines" class="sidebar-link" onclick="highlightSidebar(this)">
1323
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>
1324
+ <span data-i18n="tocEngines">2. LM Studio vs vLLM</span>
1325
+ </a>
1326
+ <ul class="sidebar-sublist">
1327
+ <li><a href="#engine-arch" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocEngines1">2.1 llama.cpp vs PagedAttn</a></li>
1328
+ <li><a href="#engine-quant" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocEngines2">2.2 GGUF Quantization Scales</a></li>
1329
+ <li><a href="#engine-flags" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocEngines3">2.3 Flag Translation Matrix</a></li>
1330
+ </ul>
1331
+ </li>
1332
+
1333
+ <!-- 3. CPU Hyper-Threading / SMT -->
1334
+ <li class="sidebar-item">
1335
+ <a href="#section-cpu-ht" class="sidebar-link" onclick="highlightSidebar(this)">
1336
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/><path d="M15 3v18"/><path d="M3 9h18"/><path d="M3 15h18"/></svg>
1337
+ <span data-i18n="tocCpuHt">3. CPU Hyper-Threading / SMT</span>
1338
+ </a>
1339
+ <ul class="sidebar-sublist">
1340
+ <li><a href="#cpu-bandwidth" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocCpu1">3.1 Memory Bandwidth Bottleneck</a></li>
1341
+ <li><a href="#cpu-thrashing" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocCpu2">3.2 L1/L2 Cache Eviction</a></li>
1342
+ <li><a href="#cpu-modes" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocCpu3">3.3 4 Thread Allocation Modes</a></li>
1343
+ </ul>
1344
+ </li>
1345
+
1346
+ <!-- 4. VRAM & Multi-GPU -->
1347
+ <li class="sidebar-item">
1348
+ <a href="#section-vram" class="sidebar-link" onclick="highlightSidebar(this)">
1349
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
1350
+ <span data-i18n="tocVram">4. VRAM Footprint &amp; Multi-GPU</span>
1351
+ </a>
1352
+ <ul class="sidebar-sublist">
1353
+ <li><a href="#vram-weights" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocVram1">4.1 Weight Memory Equation</a></li>
1354
+ <li><a href="#vram-kv" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocVram2">4.2 Hybrid KV Attention Math</a></li>
1355
+ <li><a href="#vram-overhead" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocVram3">4.3 Activation &amp; CUDA Overhead</a></li>
1356
+ <li><a href="#vram-split" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocVram4">4.4 Tensor Split Heuristic</a></li>
1357
+ </ul>
1358
+ </li>
1359
+
1360
+ <!-- 5. Zero-Key LAN Discovery -->
1361
+ <li class="sidebar-item">
1362
+ <a href="#section-lan" class="sidebar-link" onclick="highlightSidebar(this)">
1363
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M5 12.55a11 11 0 0 1 14.08 0"/><path d="M1.42 9a16 16 0 0 1 21.16 0"/><circle cx="12" cy="20" r="1"/></svg>
1364
+ <span data-i18n="tocLan">5. Zero-Key LAN Discovery</span>
1365
+ </a>
1366
+ <ul class="sidebar-sublist">
1367
+ <li><a href="#lan-scanner" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocLan1">5.1 Concurrency &amp; Sweep Budget</a></li>
1368
+ <li><a href="#lan-ports" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocLan2">5.2 Probed Ports &amp; Fingerprint</a></li>
1369
+ <li><a href="#lan-security" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocLan3">5.3 SSRF &amp; RFC1918 Guard</a></li>
1370
+ </ul>
1371
+ </li>
1372
+
1373
+ <!-- 6. Model Tuning & Commands -->
1374
+ <li class="sidebar-item">
1375
+ <a href="#section-api" class="sidebar-link" onclick="highlightSidebar(this)">
1376
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
1377
+ <span data-i18n="tocApi">6. Model Tuning &amp; Commands</span>
1378
+ </a>
1379
+ <ul class="sidebar-sublist">
1380
+ <li><a href="#cmd-cli" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocApi1">6.1 CLI &amp; Slash Commands</a></li>
1381
+ <li><a href="#params-load" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocApi2">6.2 Load Parameter Matrix</a></li>
1382
+ <li><a href="#params-sampling" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocApi3">6.3 Sampling Hyperparameters</a></li>
1383
+ <li><a href="#api-reference" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocApi4">6.4 REST API Code Playbook</a></li>
1384
+ </ul>
1385
+ </li>
1386
+
1387
+ <!-- 7. Hardware Tuning & OOM -->
1388
+ <li class="sidebar-item">
1389
+ <a href="#section-tuning" class="sidebar-link" onclick="highlightSidebar(this)">
1390
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg>
1391
+ <span data-i18n="tocTuning">7. Tuning Playbook &amp; OOM</span>
1392
+ </a>
1393
+ <ul class="sidebar-sublist">
1394
+ <li><a href="#tuning-tiers" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocTuning1">7.1 Hardware VRAM Tiers</a></li>
1395
+ <li><a href="#tuning-oom" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocTuning2">7.2 4-Step OOM Recovery</a></li>
1396
+ <li><a href="#tuning-pcie" class="sidebar-sublink" onclick="highlightSublink(this)" data-i18n="tocTuning3">7.3 PCIe Bandwidth &amp; Bus</a></li>
1397
+ </ul>
1398
+ </li>
1399
+ </ul>
1400
+ </aside>
1401
+
1402
+ <!-- Main Content Panels -->
1403
+ <main class="docs-content">
1404
+
1405
+ <!-- Hero Header -->
1406
+ <div class="docs-hero">
1407
+ <span class="docs-badge" data-i18n="heroBadge">Architecture &amp; Engineering Manual</span>
1408
+ <h1 class="docs-title" data-i18n="heroTitle">Inference Control Center Architecture</h1>
1409
+ <p class="docs-subtitle" data-i18n="heroSubtitle">คู่มือเชิงลึกและสถาปัตยกรรมทางเทคนิคของศูนย์ควบคุมการประมวลผล AI การจัดสรรทรัพยากร VRAM โครงสร้างเธรด CPU SMT และระบบค้นหาเครื่องยนต์ Local AI ภายในเครือข่าย</p>
1410
+ </div>
1411
+
1412
+ <!-- Live Detected Hardware Banner -->
1413
+ <div class="live-hw-card" id="live-hardware-card">
1414
+ <div class="live-hw-info">
1415
+ <div class="live-hw-icon">
1416
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
1417
+ </div>
1418
+ <div>
1419
+ <div class="live-hw-title" id="hw-banner-title" data-i18n="hwBannerTitle">ระบบฮาร์ดแวร์ของคุณในปัจจุบัน (Live Telemetry)</div>
1420
+ <div class="live-hw-meta" id="hw-banner-meta" data-i18n="hwBannerMeta">กำลังดึงข้อมูลเซ็นเซอร์จาก /api/v1/system/hardware...</div>
1421
+ </div>
1422
+ </div>
1423
+ <div class="live-hw-chips">
1424
+ <span class="hw-chip" id="chip-gpu">GPU: ตรวจจับอยู่...</span>
1425
+ <span class="hw-chip" id="chip-vram">VRAM: -- GB</span>
1426
+ <span class="hw-chip" id="chip-cpu">CPU: ตรวจจับอยู่...</span>
1427
+ <span class="hw-chip" id="chip-smt">SMT: --</span>
1428
+ </div>
1429
+ </div>
1430
+
1431
+ <!-- CHAPTER 1: System Architecture -->
1432
+ <section class="doc-section" id="section-arch">
1433
+ <div class="doc-section-header">
1434
+ <div class="section-icon-badge badge-cyan">
1435
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="12 2 2 7 12 12 22 7 12 2"/><polyline points="2 17 12 22 22 17"/><polyline points="2 12 12 17 22 12"/></svg>
1436
+ </div>
1437
+ <div>
1438
+ <h2 class="doc-section-title" data-i18n="sec1Title">1. สถาปัตยกรรมระบบ (System Architecture &amp; 3-Tier Data Flow)</h2>
1439
+ <p class="doc-section-desc" data-i18n="sec1Sub">โครงสร้างการสื่อสารแบบแยกส่วน Process Isolation, วงรอบการตัดสินใจ ReAct Loop และระบบจัดการหน่วยความจำถาวร</p>
1440
+ </div>
1441
+ </div>
1442
+
1443
+ <p class="doc-p" data-i18n="sec1P">
1444
+ ระบบ Kiku Agent ถูกออกแบบบนรากฐานสถาปัตยกรรม <strong>3-Tier Modular Suite Architecture</strong> เพื่อแยกกระบวนการทำงานระหว่างการแสดงผลส่วนหน้า (Presentation), การควบคุมจัดการสถานะ (Orchestration &amp; Web Server) และการคำนวณโครงข่ายประสาทเทียม (Neural Compute Engine) ออกจากกันอย่างเด็ดขาด ป้องกันไม่ให้การประมวลผลคำตอบที่ใช้ทรัพยากรสูงส่งผลกระทบต่อความลื่นไหลของ UI
1445
+ </p>
1446
+
1447
+ <!-- SUB-SECTION 1.1 -->
1448
+ <div class="sub-section" id="arch-topology">
1449
+ <h3 class="sub-title">
1450
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M3 9h18"/><path d="M9 21V9"/></svg>
1451
+ <span data-i18n="sec11Title">1.1 3-Tier Suite Topology &amp; Process Isolation</span>
1452
+ </h3>
1453
+ <p class="doc-p" data-i18n="sec11P">
1454
+ การทำงานของทั้ง 3 เลเยอร์เชื่อมต่อกันผ่านโปรโตคอลมาตรฐานที่ไร้การผูกขาด (Decoupled IPC &amp; HTTP Transport):
1455
+ </p>
1456
+
1457
+ <!-- Visual Flow Diagram -->
1458
+ <div class="arch-diagram-wrap">
1459
+ <div class="arch-level">
1460
+ <div class="arch-node">
1461
+ <div class="arch-node-title"><span style="color:var(--accent-pink);">Tier 1: Fan Portal</span> (Port 3000)</div>
1462
+ <div class="arch-node-desc" data-i18n="tier1Desc">Vite + React 19 + Tailwind CSS 4 Single Page Application (SPA) บริการข้อมูลผลงาน ประวัติ และมัลติมีเดีย ปรับปรุงด้วย Liquid Glass Design System</div>
1463
+ </div>
1464
+ <div class="arch-node">
1465
+ <div class="arch-node-title"><span style="color:var(--accent-cyan);">Tier 2: Web Chat &amp; Control Center</span> (Port 3002)</div>
1466
+ <div class="arch-node-desc" data-i18n="tier2Desc">Node.js HTTP Server ทำหน้าที่เป็น API Gateway, บริการหน้าแชทหลัก, หน้าควบคุม Inference Control Center (/settings), หน้าคู่มือ (/docs), REST API Router และ Streamable HTTP Model Context Protocol (MCP) Server (/mcp)</div>
1467
+ </div>
1468
+ </div>
1469
+ <div class="arch-arrow" data-i18n="archArrow">&#11015; OpenAI-Compatible REST, Server-Sent Events (SSE) &amp; Child Process IPC &#11015;</div>
1470
+ <div class="arch-level">
1471
+ <div class="arch-node">
1472
+ <div class="arch-node-title"><span style="color:var(--accent-emerald);">Tier 3A: LM Studio Server</span> (:1234)</div>
1473
+ <div class="arch-node-desc" data-i18n="tier3aDesc">llama.cpp Engine รองรับ Cross-Platform ทั้ง Windows, macOS (Metal) และ Linux รองรับโมเดล GGUF Quantization ผ่าน lms CLI</div>
1474
+ </div>
1475
+ <div class="arch-node">
1476
+ <div class="arch-node-title"><span style="color:var(--accent-purple);">Tier 3B: vLLM Server</span> (:8000)</div>
1477
+ <div class="arch-node-desc" data-i18n="tier3bDesc">Enterprise High-Throughput Engine ทำงานบน WSL2 / Linux พร้อมระบบจัดการ KV Cache เสมือน PagedAttention และ Continuous Batching</div>
1478
+ </div>
1479
+ <div class="arch-node">
1480
+ <div class="arch-node-title"><span style="color:var(--accent-amber);">Tier 3C: Cloud Providers</span></div>
1481
+ <div class="arch-node-desc" data-i18n="tier3cDesc">เชื่อมต่อตรงกับ API ภายนอก ได้แก่ Google Gemini, OpenAI, Groq, DeepSeek และ OpenRouter ผ่านคลาสตัวกลาง LLMClient</div>
1482
+ </div>
1483
+ </div>
1484
+ </div>
1485
+ </div>
1486
+
1487
+ <!-- SUB-SECTION 1.2 -->
1488
+ <div class="sub-section" id="arch-ipc">
1489
+ <h3 class="sub-title">
1490
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 0 0-9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M3 12a9 9 0 0 0 9 9 9.75 9.75 0 0 0 6.74-2.74L21 16"/><path d="M16 21h5v-5"/></svg>
1491
+ <span data-i18n="sec12Title">1.2 ReAct Cognitive Loop &amp; Context Compaction</span>
1492
+ </h3>
1493
+ <p class="doc-p" data-i18n="sec12P">
1494
+ สมองกลของตัวแทน AI ทำงานด้วยวงรอบ <strong>ReAct (Reasoning + Acting)</strong> โดยใช้หลักการ <em>Dynamic Multi-Factor Score Ranking</em> ในการคัดเลือกเครื่องมือ (Tools) แทนการใช้โครงสร้าง <code>if/else</code> หรือคีย์เวิร์ดตายตัว:
1495
+ </p>
1496
+ <ul style="color:var(--text-muted); font-size:13.5px; line-height:1.7; padding-left:22px; margin-bottom:16px;">
1497
+ <li data-i18n="sec12L1"><strong>Tool Priority Scoring:</strong> เครื่องมือที่ตรงเงื่อนไขจะถูกประเมินคะแนนเชิงเส้น $Score = Explicit(+100) + Priority(+20) + Direct(+10) + RankScore(15 - 3i - r)$ พร้อมเพดานโควตาคลัสเตอร์เพื่อกระจายความหลากหลายของเครื่องมือ ไม่ผูกขาดกับหมวดใดหมวดหนึ่ง</li>
1498
+ <li data-i18n="sec12L2"><strong>Context Compactor (<code>compactToolResultForContext</code>):</strong> ผลลัพธ์ดิบที่ส่งคืนจากเครื่องมือจะถูกกรองเอาลิงก์ตกแต่งและฟิลด์ฟุ่มเฟือยออก คงเหลือเฉพาะคีย์ข้อมูลสำคัญ เพื่อลดการสิ้นเปลือง Context Window และลดความหน่วง (Latency) ในการอ่านโทเค็นของ LLM</li>
1499
+ <li data-i18n="sec12L3"><strong>4-Tier Context Allocation:</strong> จัดสรรพื้นที่บริบทอย่างเป็นระบบ — 20% สำหรับคำถามของผู้ใช้, 40% สำหรับสถานะและแผนงานในหน่วยความจำแอคทีฟ, 20% สำหรับบันทึกสะท้อนผลลัพธ์ระยะยาว (Reflections), และ 20% สำหรับเครื่องมือและการสนทนาทั่วไป</li>
1500
+ </ul>
1501
+ </div>
1502
+
1503
+ <!-- SUB-SECTION 1.3 -->
1504
+ <div class="sub-section" id="arch-persistence">
1505
+ <h3 class="sub-title">
1506
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/></svg>
1507
+ <span data-i18n="sec13Title">1.3 Atomic Persistence Queue &amp; Storage Guarantees</span>
1508
+ </h3>
1509
+ <p class="doc-p" data-i18n="sec13P">
1510
+ สถานะการปรับแต่งเครื่องยนต์และการตั้งค่าอนุมานถูกจัดเก็บ 2 ระดับอย่างสมบูรณ์:
1511
+ </p>
1512
+ <div class="doc-callout callout-info">
1513
+ <div class="callout-icon">
1514
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
1515
+ </div>
1516
+ <div data-i18n="sec13Callout">
1517
+ <strong>Atomic Write Pipeline:</strong> เมื่อมีการเปลี่ยนค่าในหน้าเว็บ ข้อมูลจะถูกบันทึกลง <code>localStorage</code> ฝั่งเบราว์เซอร์ทันทีเพื่อให้ UI ตอบสนองในระดับ 0ms และส่งสัญญาณต่อไปยังเซิร์ฟเวอร์เพื่อบันทึกลงไฟล์ <code>kiku_config.json</code> ผ่านฟังก์ชันคิว <code>withSettingsWriteQueue()</code> โดยเขียนลงไฟล์ชั่วคราว <code>kiku_config.json.tmp</code> ก่อนสลับชื่อไฟล์แบบอะตอมมิก เพื่อป้องกันไฟล์เสียหายกรณีเซิร์ฟเวอร์ดับกะทันหัน 100%
1518
+ </div>
1519
+ </div>
1520
+ </div>
1521
+ </section>
1522
+
1523
+ <!-- CHAPTER 2: Engines Compared -->
1524
+ <section class="doc-section" id="section-engines">
1525
+ <div class="doc-section-header">
1526
+ <div class="section-icon-badge badge-emerald">
1527
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>
1528
+ </div>
1529
+ <div>
1530
+ <h2 class="doc-section-title" data-i18n="sec2Title">2. เปรียบเทียบเครื่องยนต์ประมวลผล (LM Studio vs vLLM)</h2>
1531
+ <p class="doc-section-desc" data-i18n="sec2Sub">ความแตกต่างเชิงสถาปัตยกรรมลึก มาตราส่วน GGUF Quantization และตารางแม็ปพารามิเตอร์ 1:1</p>
1532
+ </div>
1533
+ </div>
1534
+
1535
+ <!-- SUB-SECTION 2.1 -->
1536
+ <div class="sub-section" id="engine-arch" style="margin-top:0; border-top:none; padding-top:0;">
1537
+ <h3 class="sub-title">
1538
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m16 16 3-8 3 8c-.87.65-1.92 1-3 1s-2.13-.35-3-1Z"/><path d="m2 16 3-8 3 8c-.87.65-1.92 1-3 1s-2.13-.35-3-1Z"/><path d="M7 21h10"/><path d="M12 3v18"/></svg>
1539
+ <span data-i18n="sec21Title">2.1 llama.cpp Unified Memory vs vLLM PagedAttention</span>
1540
+ </h3>
1541
+ <p class="doc-p" data-i18n="sec21P">
1542
+ ระบบรองรับทั้งเครื่องยนต์ระดับผู้ใช้ทั่วไป (Consumer Desktop) และเครื่องยนต์ระดับศูนย์ข้อมูล (Enterprise Serving) โดยทั้งสองมีหลักการจัดสรรหน่วยความจำที่แตกต่างกัน:
1543
+ </p>
1544
+
1545
+ <div class="table-container">
1546
+ <table class="doc-table">
1547
+ <thead>
1548
+ <tr>
1549
+ <th data-i18n="sec21Th1">คุณสมบัติเชิงวิศวกรรม</th>
1550
+ <th data-i18n="sec21Th2">LM Studio (llama.cpp)</th>
1551
+ <th data-i18n="sec21Th3">vLLM (PagedAttention)</th>
1552
+ </tr>
1553
+ </thead>
1554
+ <tbody>
1555
+ <tr>
1556
+ <td><strong data-i18n="sec21R1C1">Core Architecture</strong></td>
1557
+ <td data-i18n="sec21R1C2">C/C++ CUDA, Metal, ROCm Kernels พร้อมตัวคูณเวกเตอร์ SIMD (AVX2/AVX-512)</td>
1558
+ <td data-i18n="sec21R1C3">Python/C++ Custom CUDA Kernels พัฒนาบนแนวคิด OS Virtual Memory Paging</td>
1559
+ </tr>
1560
+ <tr>
1561
+ <td><strong data-i18n="sec21R2C1">ระบบปฏิบัติการที่รองรับ</strong></td>
1562
+ <td data-i18n="sec21R2C2">Windows 10/11, macOS (Apple Silicon Metal), Linux</td>
1563
+ <td data-i18n="sec21R2C3">Linux Native หรือ Windows 11 ผ่าน WSL2 เท่านั้น (ไม่รองรับ Native Windows)</td>
1564
+ </tr>
1565
+ <tr>
1566
+ <td><strong data-i18n="sec21R3C1">รูปแบบไฟล์โมเดล</strong></td>
1567
+ <td data-i18n="sec21R3C2">GGUF Single-File Quantizations (Q4_K_M, Q6_K, Q8_0)</td>
1568
+ <td data-i18n="sec21R3C3">HuggingFace SafeTensors, AWQ, GPTQ, FP8 Checkpoints</td>
1569
+ </tr>
1570
+ <tr>
1571
+ <td><strong data-i18n="sec21R4C1">KV Cache Allocation</strong></td>
1572
+ <td data-i18n="sec21R4C2">จัดสรรบล็อกหน่วยความจำแบบต่อเนื่อง (Contiguous VRAM Buffer)</td>
1573
+ <td data-i18n="sec21R4C3">แบ่ง KV Cache เป็นเพจขนาดเล็ก (Paged Blocks) ลด Memory Fragmentation เหลือ &lt; 4%</td>
1574
+ </tr>
1575
+ <tr>
1576
+ <td><strong data-i18n="sec21R5C1">Batching Strategy</strong></td>
1577
+ <td data-i18n="sec21R5C2">Static / Dynamic Micro-batching (เน้น Single-stream Latency)</td>
1578
+ <td data-i18n="sec21R5C3">Continuous Batching (Iteration-level Scheduling) เพื่อรองรับผู้ใช้พร้อมกันจำนวนมาก</td>
1579
+ </tr>
1580
+ <tr>
1581
+ <td><strong data-i18n="sec21R6C1">ฮาร์ดแวร์เป้าหมาย</strong></td>
1582
+ <td data-i18n="sec21R6C2">การ์ดจอเดี่ยว 6GB, 8GB, 12GB หรือเครื่องไม่มีการ์ดจอ (CPU Offload)</td>
1583
+ <td data-i18n="sec21R6C3">Workstation หลายการ์ดจอ หรือ Data Center GPUs (RTX 4090, A100, H100)</td>
1584
+ </tr>
1585
+ </tbody>
1586
+ </table>
1587
+ </div>
1588
+ </div>
1589
+
1590
+ <!-- SUB-SECTION 2.2 -->
1591
+ <div class="sub-section" id="engine-quant">
1592
+ <h3 class="sub-title">
1593
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16"/><path d="M7 12h10"/><path d="M10 18h4"/></svg>
1594
+ <span data-i18n="sec22Title">2.2 GGUF Quantization Scales &amp; Bits Per Weight (BPW)</span>
1595
+ </h3>
1596
+ <p class="doc-p" data-i18n="sec22P">
1597
+ GGUF ใช้วิธีการบีบอัดน้ำหนักโมเดลแบบ K-Quants ซึ่งใช้จำนวนบิตต่อค่าน้ำหนัก (Bits Per Weight - BPW) แตกต่างกันในแต่ละเลเยอร์ โดยพิจารณาจากความไวต่อการสูญเสียข้อมูล:
1598
+ </p>
1599
+
1600
+ <div class="table-container">
1601
+ <table class="doc-table">
1602
+ <thead>
1603
+ <tr>
1604
+ <th data-i18n="sec22Th1">ระดับ Quantization</th>
1605
+ <th data-i18n="sec22Th2">BPW แท้จริง</th>
1606
+ <th data-i18n="sec22Th3">ขนาดบน VRAM (8B Model)</th>
1607
+ <th data-i18n="sec22Th4">Perplexity Delta (&Delta;PPL)</th>
1608
+ <th data-i18n="sec22Th5">คำแนะนำการใช้งาน</th>
1609
+ </tr>
1610
+ </thead>
1611
+ <tbody>
1612
+ <tr>
1613
+ <td><code>Q4_K_M</code> <span class="hw-chip" style="color:var(--accent-emerald);" data-i18n="sec22ChipRec">แนะนำ</span></td>
1614
+ <td><strong>4.50</strong></td>
1615
+ <td>~4.50 GB</td>
1616
+ <td>+0.09 PPL (แทบไม่รู้สึก)</td>
1617
+ <td data-i18n="sec22R1C5">คุ้มค่าสูงสุดสำหรับ GPU 6GB และ 8GB ให้ความเร็วและความแม่นยำสมดุลที่สุด</td>
1618
+ </tr>
1619
+ <tr>
1620
+ <td><code>Q5_K_M</code></td>
1621
+ <td><strong>5.50</strong></td>
1622
+ <td>~5.50 GB</td>
1623
+ <td>+0.04 PPL</td>
1624
+ <td data-i18n="sec22R2C5">เหมาะสำหรับผู้ใช้ที่ต้องการคำตอบภาษาไทยและจีนที่สมบูรณ์ขึ้น บนการ์ด 8GB–12GB</td>
1625
+ </tr>
1626
+ <tr>
1627
+ <td><code>Q6_K</code></td>
1628
+ <td><strong>6.56</strong></td>
1629
+ <td>~6.56 GB</td>
1630
+ <td>+0.01 PPL (Near-Lossless)</td>
1631
+ <td data-i18n="sec22R3C5">คุณภาพเทียบเคียง FP16 เหมาะสำหรับการ์ดจอ 12GB ขึ้นไป เช่น RTX 4070</td>
1632
+ </tr>
1633
+ <tr>
1634
+ <td><code>Q8_0</code></td>
1635
+ <td><strong>8.00</strong></td>
1636
+ <td>~8.00 GB</td>
1637
+ <td>0.00 PPL (Lossless 8-bit)</td>
1638
+ <td data-i18n="sec22R4C5">มาตรฐานสำหรับการประเมินผล Benchmarking และการคำนวณขั้นสูงบน GPU 16GB+</td>
1639
+ </tr>
1640
+ <tr>
1641
+ <td><code>FP16</code></td>
1642
+ <td><strong>16.00</strong></td>
1643
+ <td>~16.00 GB</td>
1644
+ <td>0.00 Baseline</td>
1645
+ <td data-i18n="sec22R5C5">น้ำหนักดั้งเดิมก่อนควอนต์ ใช้สำหรับวิจัยหรือ Fine-tuning</td>
1646
+ </tr>
1647
+ </tbody>
1648
+ </table>
1649
+ </div>
1650
+ </div>
1651
+
1652
+ <!-- SUB-SECTION 2.3 -->
1653
+ <div class="sub-section" id="engine-flags">
1654
+ <h3 class="sub-title">
1655
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
1656
+ <span data-i18n="sec23Title">2.3 Flag Translation Matrix: LM Studio (lms) vs vLLM CLI</span>
1657
+ </h3>
1658
+ <p class="doc-p" data-i18n="sec23P">
1659
+ ตารางเทียบเคียงคำสั่งพารามิเตอร์ 1:1 เพื่อให้นักพัฒนาสามารถสลับการควบคุมระหว่าง LM Studio และ vLLM ได้อย่างแม่นยำ:
1660
+ </p>
1661
+
1662
+ <div class="table-container">
1663
+ <table class="doc-table">
1664
+ <thead>
1665
+ <tr>
1666
+ <th data-i18n="sec23Th1">หน้าที่การควบคุม</th>
1667
+ <th data-i18n="sec23Th2">LM Studio (<code>lms load</code>)</th>
1668
+ <th data-i18n="sec23Th3">vLLM (<code>python -m vllm.entrypoints.openai.api_server</code>)</th>
1669
+ </tr>
1670
+ </thead>
1671
+ <tbody>
1672
+ <tr>
1673
+ <td><strong data-i18n="sec23R1C1">การดึงโมเดลเข้า VRAM</strong></td>
1674
+ <td><code>--gpu max</code> หรือ <code>--gpu 0.85</code></td>
1675
+ <td><code>--gpu-memory-utilization 0.90</code></td>
1676
+ </tr>
1677
+ <tr>
1678
+ <td><strong data-i18n="sec23R2C1">ความยาว Context Window</strong></td>
1679
+ <td><code>--context-length 32768</code></td>
1680
+ <td><code>--max-model-len 32768</code></td>
1681
+ </tr>
1682
+ <tr>
1683
+ <td><strong data-i18n="sec23R3C1">จำนวนคำขอพร้อมกัน (Slots)</strong></td>
1684
+ <td><code>--parallel 6</code></td>
1685
+ <td><code>--max-num-seqs 6</code></td>
1686
+ </tr>
1687
+ <tr>
1688
+ <td><strong data-i18n="sec23R4C1">Attention Acceleration</strong></td>
1689
+ <td><code>--flash-attn</code> (FlashAttention-2)</td>
1690
+ <td data-i18n="sec23R4C3">เปิดทำงานโดยอัตโนมัติ (หรือใช้ <code>--enforce-eager</code> เพื่อปิด)</td>
1691
+ </tr>
1692
+ <tr>
1693
+ <td><strong data-i18n="sec23R5C1">การแบ่งโมเดลหลาย GPU</strong></td>
1694
+ <td><code>--split-mode layer --tensor-split 20,12</code></td>
1695
+ <td><code>--tensor-parallel-size 2</code></td>
1696
+ </tr>
1697
+ <tr>
1698
+ <td><strong data-i18n="sec23R6C1">การบีบอัด KV Cache</strong></td>
1699
+ <td><code>--ctk q8_0 --ctv q8_0</code></td>
1700
+ <td><code>--kv-cache-dtype fp8</code></td>
1701
+ </tr>
1702
+ </tbody>
1703
+ </table>
1704
+ </div>
1705
+ </div>
1706
+ </section>
1707
+
1708
+ <!-- CHAPTER 3: CPU Hyper-Threading / SMT -->
1709
+ <section class="doc-section" id="section-cpu-ht">
1710
+ <div class="doc-section-header">
1711
+ <div class="section-icon-badge badge-amber">
1712
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/><path d="M15 3v18"/><path d="M3 9h18"/><path d="M3 15h18"/></svg>
1713
+ </div>
1714
+ <div>
1715
+ <h2 class="doc-section-title" data-i18n="sec3Title">3. การจัดการ CPU Hyper-Threading &amp; SMT Topology</h2>
1716
+ <p class="doc-section-desc" data-i18n="sec3Sub">หลักการทางฟิสิกส์: ขีดจำกัด Memory Bandwidth, การแย่งแคช L1/L2 และสถาปัตยกรรมเธรด 4 โหมด</p>
1717
+ </div>
1718
+ </div>
1719
+
1720
+ <!-- SUB-SECTION 3.1 -->
1721
+ <div class="sub-section" id="cpu-bandwidth" style="margin-top:0; border-top:none; padding-top:0;">
1722
+ <h3 class="sub-title">
1723
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="12" y1="2" x2="12" y2="6"/><line x1="12" y1="18" x2="12" y2="22"/><line x1="4.93" y1="4.93" x2="7.76" y2="7.76"/><line x1="16.24" y1="16.24" x2="19.07" y2="19.07"/><line x1="2" y1="12" x2="6" y2="12"/><line x1="18" y1="12" x2="22" y2="12"/><line x1="4.93" y1="19.07" x2="7.76" y2="16.24"/><line x1="16.24" y1="7.76" x2="19.07" y2="4.93"/></svg>
1724
+ <span data-i18n="sec31Title">3.1 Memory Bandwidth Bottleneck &amp; Compute Bounds</span>
1725
+ </h3>
1726
+ <p class="doc-p" data-i18n="sec31P">
1727
+ ในการอนุมานผลลัพธ์ของโมเดลภาษา (Autoregressive Token Generation) ทุกๆ 1 โทเค็นที่สร้างขึ้น ซีพียูต้องโหลดน้ำหนักโมเดลทั้งหมด (Weights) ผ่านบัสหน่วยความจำอย่างน้อย 1 รอบเต็มเสมอ:
1728
+ </p>
1729
+
1730
+ <div class="formula-card">
1731
+ <div class="formula-math" data-i18n="sec31MathMain">Maximum Tokens/sec &le; Memory Bandwidth (GB/s) &divide; Model Weight Size (GB)</div>
1732
+ <div class="formula-sub" data-i18n="sec31MathSub">สมการขีดจำกัดความเร็วสูงสุดทางทฤษฎีของการสร้างโทเค็นบนระบบ Memory-Bound</div>
1733
+ </div>
1734
+
1735
+ <p class="doc-p" data-i18n="sec31P2">
1736
+ เปรียบเทียบแบนด์วิดท์จริงระหว่างหน่วยความจำหลัก (RAM) และหน่วยความจำการ์ดจอ (VRAM):
1737
+ </p>
1738
+ <ul style="color:var(--text-muted); font-size:13.5px; line-height:1.7; padding-left:22px;">
1739
+ <li data-i18n="sec31L1"><strong>Dual-Channel DDR4-3200:</strong> แบนด์วิดท์สูงสุด ~45–50 GB/s &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วสูงสุดไม่เกิน <strong>10–11 tokens/s</strong></li>
1740
+ <li data-i18n="sec31L2"><strong>Dual-Channel DDR5-6000:</strong> แบนด์วิดท์สูงสุด ~85–96 GB/s &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วสูงสุดไม่เกิน <strong>18–21 tokens/s</strong></li>
1741
+ <li data-i18n="sec31L3"><strong>RTX 3060 GDDR6 (192-bit):</strong> แบนด์วิดท์ <strong>360 GB/s</strong> &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็ว <strong>70–80 tokens/s</strong></li>
1742
+ <li data-i18n="sec31L4"><strong>RTX 4090 GDDR6X (384-bit):</strong> แบนด์วิดท์ <strong>1,008 GB/s</strong> &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วทะลุ <strong>150+ tokens/s</strong></li>
1743
+ </ul>
1744
+ </div>
1745
+
1746
+ <!-- SUB-SECTION 3.2 -->
1747
+ <div class="sub-section" id="cpu-thrashing">
1748
+ <h3 class="sub-title">
1749
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
1750
+ <span data-i18n="sec32Title">3.2 SMT / Hyper-Threading Cache Eviction &amp; Pipeline Thrashing</span>
1751
+ </h3>
1752
+ <p class="doc-p" data-i18n="sec32P">
1753
+ เทคโนโลยี Simultaneous Multi-Threading (SMT ใน AMD หรือ Hyper-Threading ใน Intel) สร้าง Logical Threads เสมือนขึ้นมา 2 ตัวบนคอร์จริงอันเดียว แต่ทั้งสองเธรดต้องใช้ทรัพยากรฮาร์ดแวร์ภายในร่วมกัน:
1754
+ </p>
1755
+ <div class="doc-callout callout-warn">
1756
+ <div class="callout-icon">
1757
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
1758
+ </div>
1759
+ <div data-i18n="sec32Warn">
1760
+ <strong>ทำไม SMT ทำให้ LLM ช้าลง:</strong> การคูณเมทริกซ์ของ LLM รันบนหน่วยคำนวณทศนิยม (Floating Point Units / AVX2 / AVX-512) อย่างเข้มข้น 100% ต่อเนื่อง หากส่งเธรดคำนวณเข้าไป 2 เธรดพร้อมกัน เธรดทั้งสองจะเกิดการชนกันที่ Execution Ports และที่สำคัญที่สุดคือจะ <strong>ขับไล่ข้อมูลในแคช L1 และ L2 ทิ้ง (Cache Eviction)</strong> ส่งผลให้เกิด Cache Misses มหาศาล อัตราความเร็วในการสร้างโทเค็นจะ <strong>ร่วงลง 10% ถึง 25%!</strong>
1761
+ </div>
1762
+ </div>
1763
+ </div>
1764
+
1765
+ <!-- SUB-SECTION 3.3 -->
1766
+ <div class="sub-section" id="cpu-modes">
1767
+ <h3 class="sub-title">
1768
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg>
1769
+ <span data-i18n="sec33Title">3.3 The 4 Thread Allocation Modes ใน <code>cpuMetrics.js</code></span>
1770
+ </h3>
1771
+ <div class="table-container">
1772
+ <table class="doc-table">
1773
+ <thead>
1774
+ <tr>
1775
+ <th data-i18n="sec33Th1">โหมด (htMode)</th>
1776
+ <th data-i18n="sec33Th2">สูตรคำนวณจำนวนเธรด</th>
1777
+ <th data-i18n="sec33Th3">พฤติกรรมและการจัดสรรทรัพยากร</th>
1778
+ </tr>
1779
+ </thead>
1780
+ <tbody>
1781
+ <tr>
1782
+ <td><code>physical</code> <span class="hw-chip" style="color:var(--accent-emerald);" data-i18n="sec33ChipRec">โหมดแนะนำสูงสุด</span></td>
1783
+ <td><code>Math.min(physicalCores, 12)</code></td>
1784
+ <td data-i18n="sec33R1C3">ล็อคจำนวนเธรดเท่ากับคอร์แท้เท่านั้น ขจัดปัญหาการแย่งแคช L1/L2 ให้ Single-stream latency ต่ำที่สุดและความเร็วสูงสุดสำหรับการแชท 1 ต่อ 1</td>
1785
+ </tr>
1786
+ <tr>
1787
+ <td><code>smt</code> / <code>all</code></td>
1788
+ <td><code>logicalThreads</code> (เช่น 12 หรือ 16 เธรด)</td>
1789
+ <td data-i18n="sec33R2C3">เปิดใช้ทุกเธรดเสมือน เหมาะสำหรับสถานการณ์ที่ต้องการประมวลผลคำขอ Prompt Prefill พร้อมกันหลายผู้ใช้ (Throughput-oriented)</td>
1790
+ </tr>
1791
+ <tr>
1792
+ <td><code>auto</code></td>
1793
+ <td data-i18n="sec33R3C2">Heuristic จากสถาปัตยกรรม CPU</td>
1794
+ <td data-i18n="sec33R3C3">ตรวจจับโครงสร้างคอร์อัตโนมัติ หากตรวจพบว่าเป็นระบบที่มี SMT จะสงวนคอร์ไว้ 1-2 คอร์สำหรับงาน OS และ I/O</td>
1795
+ </tr>
1796
+ <tr>
1797
+ <td><code>custom</code></td>
1798
+ <td data-i18n="sec33R4C2">ผู้ใช้ระบุค่าอิสระ (1–256)</td>
1799
+ <td data-i18n="sec33R4C3">ยืดหยุ่นตามความต้องการของผู้ดูแลระบบ เหมาะสำหรับเซิร์ฟเวอร์แบบ NUMA Multi-Socket</td>
1800
+ </tr>
1801
+ </tbody>
1802
+ </table>
1803
+ </div>
1804
+ </div>
1805
+ </section>
1806
+
1807
+ <!-- CHAPTER 4: VRAM Footprint & Multi-GPU -->
1808
+ <section class="doc-section" id="section-vram">
1809
+ <div class="doc-section-header">
1810
+ <div class="section-icon-badge badge-purple">
1811
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
1812
+ </div>
1813
+ <div>
1814
+ <h2 class="doc-section-title" data-i18n="sec4Title">4. การคำนวณ VRAM Footprint &amp; Multi-GPU Math</h2>
1815
+ <p class="doc-section-desc" data-i18n="sec4Sub">สูตรคำนวณทางคณิตศาสตร์ที่แม่นยำของ Model Weights, Hybrid SWA Attention และการจัดสรร Multi-GPU</p>
1816
+ </div>
1817
+ </div>
1818
+
1819
+ <div class="formula-card">
1820
+ <div class="formula-math" data-i18n="sec4MathMain">Total VRAM Footprint = Weight Memory + KV Cache Memory + Activation &amp; CUDA Overhead</div>
1821
+ <div class="formula-sub" data-i18n="sec4MathSub">งบประมาณหน่วยความจำวิดีโอทั้งหมดที่ต้องจัดสรรล่วงหน้าก่อนรันโมเดล</div>
1822
+ </div>
1823
+
1824
+ <!-- SUB-SECTION 4.1 -->
1825
+ <div class="sub-section" id="vram-weights">
1826
+ <h3 class="sub-title">
1827
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2v20"/><path d="M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6"/></svg>
1828
+ <span data-i18n="sec41Title">4.1 Weight Memory Equation &amp; BPW Math</span>
1829
+ </h3>
1830
+ <p class="doc-p" data-i18n="sec41P">
1831
+ หน่วยความจำสำหรับบรรจุน้ำหนักโมเดลคำนวณจากจำนวนพารามิเตอร์คูณด้วย Bits Per Weight (BPW) หารด้วย 8:
1832
+ </p>
1833
+ <div class="formula-card">
1834
+ <div class="formula-math">Weight Memory (GB) = (Parameters &times; BPW) &divide; (8 &times; 1024&sup3;)</div>
1835
+ <div class="formula-sub" data-i18n="sec41MathSub">ตัวอย่าง: โมเดล Gemma 4 E4B (8.0B parameters) ที่ Q4_K_M (BPW = 4.50) = (8.0 &times; 10&sup9; &times; 4.50) &divide; (8 &times; 1024&sup3;) &asymp; 4.19 GiB (4.50 GB)</div>
1836
+ </div>
1837
+ <p class="doc-p" data-i18n="sec41P2">
1838
+ กรณีที่มีการกระจายชั้นเลเยอร์บางส่วน (Fractional Offload):
1839
+ <br><code>Offloaded Weights (GB) = Total Weight Memory &times; (GPU Layers &divide; Total Layers)</code>
1840
+ </p>
1841
+ </div>
1842
+
1843
+ <!-- SUB-SECTION 4.2 -->
1844
+ <div class="sub-section" id="vram-kv">
1845
+ <h3 class="sub-title">
1846
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
1847
+ <span data-i18n="sec42Title">4.2 Hybrid KV Attention Math &amp; Sliding Window (SWA)</span>
1848
+ </h3>
1849
+ <p class="doc-p" data-i18n="sec42P">
1850
+ สถาปัตยกรรม <strong>Gemma 4</strong> ไม่ได้ใช้ Attention แบบเต็มความยาวในทุกเลเยอร์ แต่ใช้ระบบลูกผสม <strong>Sliding Window Attention (SWA Profile) อัตราส่วน 5:1</strong>:
1851
+ </p>
1852
+ <ul style="color:var(--text-muted); font-size:13.5px; line-height:1.7; padding-left:22px; margin-bottom:14px;">
1853
+ <li data-i18n="sec42L1"><strong>Local Sliding Layers (5 ใน 6 เลเยอร์):</strong> บันทึก KV Cache เฉพาะหน้าต่าง 1,024 โทเค็นล่าสุดเท่านั้น (ความจำจะถูก Clamp ไว้ที่ 1,024 ไม่ว่า Context จะยาว 32K หรือ 64K ก็ตาม)</li>
1854
+ <li data-i18n="sec42L2"><strong>Global Layers (1 ใน 6 เลเยอร์):</strong> บันทึกประวัติศาสตร์บริบทแบบเต็มความยาว Context Length ($L_{ctx}$)</li>
1855
+ </ul>
1856
+ <div class="formula-card">
1857
+ <div class="formula-math">KV Cache Total = (Layers_Global &times; 2 &times; H &times; D &times; B_val &times; L_ctx) + (Layers_Local &times; 2 &times; H &times; D &times; B_val &times; min(L_ctx, 1024))</div>
1858
+ <div class="formula-sub" data-i18n="sec42MathSub">H = Attention Heads, D = Head Dimension, B_val = Bytes Per Value ตามระดับการควอนต์</div>
1859
+ </div>
1860
+ <p class="doc-p" data-i18n="sec42P2">
1861
+ การลดขนาด KV Cache ตามชนิดข้อมูล (<code>KV_CACHE_DTYPE_BYTES</code>):
1862
+ <br>&bull; <code>fp16</code>: 2.00 Bytes/Value &bull; <code>q8_0</code>: 1.0625 Bytes/Value (ลดลง ~47%) &bull; <code>q4_0</code>: 0.5625 Bytes/Value (ลดลง ~72%)
1863
+ </p>
1864
+ </div>
1865
+
1866
+ <!-- SUB-SECTION 4.3 -->
1867
+ <div class="sub-section" id="vram-overhead">
1868
+ <h3 class="sub-title">
1869
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
1870
+ <span data-i18n="sec43Title">4.3 Activation Buffers &amp; CUDA Runtime Overhead</span>
1871
+ </h3>
1872
+ <p class="doc-p" data-i18n="sec43P">
1873
+ พื้นที่กันชนส่วนเกินคำนวณตามสูตรใน <code>src/lib/vram/estimator.js</code>:
1874
+ </p>
1875
+ <ul style="color:var(--text-muted); font-size:13.5px; line-height:1.7; padding-left:22px;">
1876
+ <li data-i18n="sec43L1"><strong>CUDA Context:</strong> พื้นที่สำหรับ CUDA Driver, Unified Virtual Addressing และโครงสร้าง Kernel ระหว่าง 0.35 GB ถึง 0.55 GB</li>
1877
+ <li data-i18n="sec43L2"><strong>Intermediate Activations:</strong> อยู่ในช่วง 0.15 GB ถึง 0.35 GB (ค่าเริ่มต้น 0.25 GB) สำหรับจัดเก็บผลลัพธ์ระหว่างชั้นเลเยอร์</li>
1878
+ <li data-i18n="sec43L3"><strong>LM Studio Engine Overhead:</strong> พื้นที่กันชน $0.60 \text{ GB} + 0.10 \text{ GB} \times N_{GPUs}$ เพื่อป้องกันไดรเวอร์ NVIDIA แคชล้นจนเกิด Display Driver Crash (TDR)</li>
1879
+ </ul>
1880
+ </div>
1881
+
1882
+ <!-- SUB-SECTION 4.4 -->
1883
+ <div class="sub-section" id="vram-split">
1884
+ <h3 class="sub-title">
1885
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/></svg>
1886
+ <span data-i18n="sec44Title">4.4 Multi-GPU Tensor Split &amp; Balancing Heuristics</span>
1887
+ </h3>
1888
+ <p class="doc-p" data-i18n="sec44P">
1889
+ เมื่อใช้งานเครื่องที่มีการ์ดจอมากกว่า 1 ใบ ระบบรองรับกลยุทธ์การกระจายโมเดล 2 รูปแบบ:
1890
+ </p>
1891
+ <div class="table-container">
1892
+ <table class="doc-table">
1893
+ <thead>
1894
+ <tr>
1895
+ <th data-i18n="sec44Th1">กลยุทธ์</th>
1896
+ <th data-i18n="sec44Th2">พารามิเตอร์</th>
1897
+ <th data-i18n="sec44Th3">การเชื่อมต่อที่เหมาะสม</th>
1898
+ <th data-i18n="sec44Th4">ข้อดีและข้อจำกัด</th>
1899
+ </tr>
1900
+ </thead>
1901
+ <tbody>
1902
+ <tr>
1903
+ <td><strong>Layer Split</strong></td>
1904
+ <td><code>--split-mode layer</code></td>
1905
+ <td data-i18n="sec44R1C3">PCIe Gen3 / Gen4 ธรรมดา (ไม่จำเป็นต้องมีบริดจ์)</td>
1906
+ <td data-i18n="sec44R1C4">แบ่งเลเยอร์ตามชั้น เหมาะสำหรับการ์ดจอที่มีขนาด VRAM ต่างกัน เช่น RTX 4080 (16GB) คู่กับ RTX 3060 (12GB) โดยกำหนดสัดส่วน <code>--tensor-split 16,12</code></td>
1907
+ </tr>
1908
+ <tr>
1909
+ <td><strong>Row Split</strong></td>
1910
+ <td><code>--split-mode row</code></td>
1911
+ <td data-i18n="sec44R2C3">NVLink บริดจ์ความเร็วสูง หรือ PCIe 4.0 x16</td>
1912
+ <td data-i18n="sec44R2C4">ตัดแบ่งเมทริกซ์ภายในเลเยอร์ด้วย Tensor Parallelism ได้ Throughput สูงสุด แต่ต้องการการ์ดจอที่มีสเปกเหมือนกัน</td>
1913
+ </tr>
1914
+ </tbody>
1915
+ </table>
1916
+ </div>
1917
+ </div>
1918
+ </section>
1919
+
1920
+ <!-- CHAPTER 5: Zero-Key LAN Discovery -->
1921
+ <section class="doc-section" id="section-lan">
1922
+ <div class="doc-section-header">
1923
+ <div class="section-icon-badge badge-cyan">
1924
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M5 12.55a11 11 0 0 1 14.08 0"/><path d="M1.42 9a16 16 0 0 1 21.16 0"/><circle cx="12" cy="20" r="1"/></svg>
1925
+ </div>
1926
+ <div>
1927
+ <h2 class="doc-section-title" data-i18n="sec5Title">5. ระบบค้นหาเครือข่ายภายใน (Zero-Key LAN Discovery)</h2>
1928
+ <p class="doc-section-desc" data-i18n="sec5Sub">เทคโนโลยีสแกนค้นหาเครื่องแม่ข่าย AI ในวงแลนอัตโนมัติ การแยกแยะพอร์ต และกำแพงป้องกัน SSRF</p>
1929
+ </div>
1930
+ </div>
1931
+
1932
+ <!-- SUB-SECTION 5.1 -->
1933
+ <div class="sub-section" id="lan-scanner" style="margin-top:0; border-top:none; padding-top:0;">
1934
+ <h3 class="sub-title">
1935
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="m4.93 4.93 4.24 4.24"/><path d="m14.83 9.17 4.24-4.24"/><path d="m14.83 14.83 4.24 4.24"/><path d="m9.17 14.83-4.24 4.24"/></svg>
1936
+ <span data-i18n="sec51Title">5.1 Network Interface Inspection &amp; Concurrency Sweeper</span>
1937
+ </h3>
1938
+ <p class="doc-p" data-i18n="sec51P">
1939
+ ระบบ <code>scanLan()</code> ใน <code>server/agent/lanDiscovery.js</code> ออกแบบมาเพื่อตรวจจับเครื่องแม่ข่าย AI ท้องถิ่นโดยที่ผู้ใช้ไม่ต้องเปิดเทอร์มินัลพิมพ์คำสั่ง <code>ipconfig</code> หรือป้อนที่อยู่ IP เอง:
1940
+ </p>
1941
+ <ul style="color:var(--text-muted); font-size:13.5px; line-height:1.7; padding-left:22px;">
1942
+ <li data-i18n="sec51L1"><strong>Cross-Platform Inspection:</strong> ตรวจจับการ์ดแลนและการ์ด Wi-Fi ผ่าน <code>os.networkInterfaces()</code> เสริมด้วย PowerShell Snapshot บน Windows (<code>Get-NetAdapter</code> + <code>Get-NetRoute</code>) หรือ <code>ip -j addr</code> บน Linux เพื่อนำ Netmask แท้จริงมาใช้คำนวณ Subnet</li>
1943
+ <li data-i18n="sec51L2"><strong>Bounded Concurrency Pool:</strong> ใช้ระบบ TCP Connect Pre-filter แบบจำกัดปริมาณ Socket พร้อมกัน (~64 โฮสต์พร้อมกัน) เพื่อสแกนตรวจจับเป้าหมาย 2,500–3,000 จุด ให้เสร็จสิ้นภายในเวลาเพียง 15–20 วินาที โดยไม่ทำให้เราเตอร์ในบ้านค้าง</li>
1944
+ <li data-i18n="sec51L3"><strong>Auto-Sweep Budget Packing:</strong> จัดเรียง Subnet จากขนาดเล็กไปใหญ่ และข้าม Subnet ที่มีขนาดเกินโควตาความปลอดภัย (<code>KIKU_LAN_SCAN_MAX_HOSTS = 4096</code>) เพื่อป้องกันการสแกนค้าง</li>
1945
+ </ul>
1946
+ </div>
1947
+
1948
+ <!-- SUB-SECTION 5.2 -->
1949
+ <div class="sub-section" id="lan-ports">
1950
+ <h3 class="sub-title">
1951
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="2" width="20" height="8" rx="2" ry="2"/><rect x="2" y="14" width="20" height="8" rx="2" ry="2"/><line x1="6" y1="6" x2="6.01" y2="6"/><line x1="6" y1="18" x2="6.01" y2="18"/></svg>
1952
+ <span data-i18n="sec52Title">5.2 Probed Ports &amp; Server Fingerprinting</span>
1953
+ </h3>
1954
+ <p class="doc-p" data-i18n="sec52P">
1955
+ ทุกพอร์ตที่เปิดจะถูกตรวจสอบเชิงลึกเพื่อระบุชนิดของเครื่องยนต์และดึงรายชื่อโมเดลที่กำลังโหลดอยู่:
1956
+ </p>
1957
+ <div class="table-container">
1958
+ <table class="doc-table">
1959
+ <thead>
1960
+ <tr>
1961
+ <th data-i18n="sec52Th1">พอร์ตเป้าหมาย</th>
1962
+ <th data-i18n="sec52Th2">เครื่องยนต์ที่คาดหวัง</th>
1963
+ <th data-i18n="sec52Th3">จุดตรวจสอบ Fingerprint</th>
1964
+ <th data-i18n="sec52Th4">ข้อมูลที่ส่งคืน</th>
1965
+ </tr>
1966
+ </thead>
1967
+ <tbody>
1968
+ <tr>
1969
+ <td><code>1234</code></td>
1970
+ <td><strong>LM Studio</strong></td>
1971
+ <td><code>/api/v0/models</code> &rarr; <code>/v1/models</code></td>
1972
+ <td data-i18n="sec52R1C4">สถานะการโหลด, Quantization, Loaded Context Length</td>
1973
+ </tr>
1974
+ <tr>
1975
+ <td><code>8000</code></td>
1976
+ <td><strong>vLLM</strong></td>
1977
+ <td><code>/version</code> &rarr; <code>/v1/models</code></td>
1978
+ <td data-i18n="sec52R2C4">เวอร์ชัน vLLM, สถาปัตยกรรมโมเดล, Max Model Len</td>
1979
+ </tr>
1980
+ <tr>
1981
+ <td><code>11434</code></td>
1982
+ <td><strong>Ollama</strong></td>
1983
+ <td><code>/api/tags</code></td>
1984
+ <td data-i18n="sec52R3C4">Tag โมเดลที่ดาวน์โหลดไว้ในระบบ</td>
1985
+ </tr>
1986
+ <tr>
1987
+ <td><code>8080</code></td>
1988
+ <td><strong>Generic llama.cpp</strong></td>
1989
+ <td><code>/v1/models</code> &rarr; <code>/health</code></td>
1990
+ <td data-i18n="sec52R4C4">เวลาตอบสนอง (Round-Trip Latency) และรายชื่อโมเดล</td>
1991
+ </tr>
1992
+ </tbody>
1993
+ </table>
1994
+ </div>
1995
+ </div>
1996
+
1997
+ <!-- SUB-SECTION 5.3 -->
1998
+ <div class="sub-section" id="lan-security">
1999
+ <h3 class="sub-title">
2000
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
2001
+ <span data-i18n="sec53Title">5.3 SSRF Defense, RFC1918 Pinning &amp; Security Guard</span>
2002
+ </h3>
2003
+ <div class="doc-callout callout-warn">
2004
+ <div class="callout-icon">
2005
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
2006
+ </div>
2007
+ <div data-i18n="sec53Warn">
2008
+ <strong>การป้องกัน Server-Side Request Forgery (SSRF):</strong> โมดูล LAN Scanner มีระบบตรวจสอบที่อยู่เครือข่ายอย่างเข้มงวด โดยจำกัดขอบเขตการกวาดตรวจเฉพาะช่วง <strong>RFC1918 Private IPv4</strong> (<code>10.0.0.0/8</code>, <code>172.16.0.0/12</code>, <code>192.168.0.0/16</code>) และ Loopback (<code>127.0.0.1</code>) เท่านั้น หากมีการระบุ IP สาธารณะ หรือ Cloud Metadata Range (<code>169.254.169.254</code>) ระบบจะปฏิเสธคำขอทันที พร้อมทั้งจำกัดสิทธิ์การกด Apply ข้ามเครื่องให้เฉพาะ Local Loopback เท่านั้น
2009
+ </div>
2010
+ </div>
2011
+ </div>
2012
+ </section>
2013
+
2014
+ <!-- CHAPTER 6: Model Tuning & Commands (THE HIGHLIGHTED SECTION) -->
2015
+ <section class="doc-section" id="section-api">
2016
+ <div class="doc-section-header">
2017
+ <div class="section-icon-badge badge-pink">
2018
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
2019
+ </div>
2020
+ <div>
2021
+ <h2 class="doc-section-title" data-i18n="sec6Title">6. คู่มือคำสั่งและการปรับแต่งโมเดลเชิงลึก (Model Tuning &amp; Commands)</h2>
2022
+ <p class="doc-section-desc" data-i18n="sec6Sub">สารานุกรมคำสั่ง CLI แบบครบถ้วน, พารามิเตอร์การโหลดโมเดลเข้า VRAM และ Hyperparameters สำหรับ Sampling</p>
2023
+ </div>
2024
+ </div>
2025
+
2026
+ <p class="doc-p" data-i18n="sec6P">
2027
+ ส่วนนี้รวบรวมข้อมูลเชิงเทคนิคของการควบคุมโมเดล AI ในระบบ Kiku ทั้งหมด ตั้งแต่การใช้งานผ่าน Command Line Interface (CLI), การปรับแต่งพารามิเตอร์โหลดเข้าการ์ดจอ ไปจนถึงการจูนพารามิเตอร์สุ่มคำตอบ (Sampling Hyperparameters)
2028
+ </p>
2029
+
2030
+ <!-- SUB-SECTION 6.1 -->
2031
+ <div class="sub-section" id="cmd-cli">
2032
+ <h3 class="sub-title">
2033
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/></svg>
2034
+ <span data-i18n="sec61Title">6.1 สารานุกรมคำสั่ง CLI &amp; Interactive Slash Commands</span>
2035
+ </h3>
2036
+ <p class="doc-p" data-i18n="sec61P">
2037
+ ระบบรองรับคำสั่งทั้งในรูปแบบ One-Shot CLI สำหรับการสคริปต์อัตโนมัติ และ Interactive Slash Commands ภายในเทอร์มินัลหรือแชท:
2038
+ </p>
2039
+
2040
+ <div class="cmd-grid">
2041
+ <!-- CMD 1: kiku-agent CLI -->
2042
+ <div class="cmd-card">
2043
+ <div class="cmd-syntax-bar">
2044
+ <span class="cmd-syntax">npx kiku-agent --query "&lt;prompt&gt;" [--provider &lt;name&gt;] [--model &lt;id&gt;]</span>
2045
+ <span class="cmd-tag">One-Shot CLI</span>
2046
+ </div>
2047
+ <p class="cmd-desc" data-i18n="cmd1Desc">
2048
+ รันคำสั่งถามตอบแบบครั้งเดียวจบ (Headless Execution) ทำงานผ่าน ReAct Agent เต็มรูปแบบ ค้นหาข้อมูลผลงาน ละคร เพลง และเว็บริเสิร์ชอัตโนมัติ เหมาะสำหรับตั้งเวลา Cron หรือไปป์คำสั่ง
2049
+ </p>
2050
+ </div>
2051
+
2052
+ <!-- CMD 2: /lan -->
2053
+ <div class="cmd-card">
2054
+ <div class="cmd-syntax-bar">
2055
+ <span class="cmd-syntax">/lan [scan | ifs | use &lt;n&gt; [model] | json]</span>
2056
+ <span class="cmd-tag">Network Engine</span>
2057
+ </div>
2058
+ <p class="cmd-desc" data-i18n="cmd2Desc">
2059
+ กวาดสแกนหาเครื่องแม่ข่าย AI ภายในวงแลน (<code>/lan ifs</code> แสดงการ์ดเครือข่าย, <code>/lan scan --iface Wi-Fi</code> สแกนเฉพาะการ์ดนั้น, <code>/lan use 1</code> สลับไปเชื่อมต่อกับโฮสต์และพอร์ตของเครื่องที่ 1 พร้อมบันทึก Base URL อัตโนมัติ)
2060
+ </p>
2061
+ </div>
2062
+
2063
+ <!-- CMD 3: /model -->
2064
+ <div class="cmd-card">
2065
+ <div class="cmd-syntax-bar">
2066
+ <span class="cmd-syntax">/model [status | load &lt;id&gt; | unload | config | temp | topp | minp | ctx]</span>
2067
+ <span class="cmd-tag">Inference Control</span>
2068
+ </div>
2069
+ <p class="cmd-desc" data-i18n="cmd3Desc">
2070
+ จัดการโมเดลและเครื่องยนต์ที่กำลังรันอยู่ ปรับแต่งอุณหภูมิ Sampling (<code>/model temp 0.2</code>), ปรับ Context Limit (<code>/model ctx 32768</code>), สั่งคืน VRAM (<code>/model unload</code>) หรือตรวจสอบสถานะการโหลด
2071
+ </p>
2072
+ </div>
2073
+
2074
+ <!-- CMD 4: /provider -->
2075
+ <div class="cmd-card">
2076
+ <div class="cmd-syntax-bar">
2077
+ <span class="cmd-syntax">/provider [list | use &lt;name&gt; [model] | url [provider] [url] | models]</span>
2078
+ <span class="cmd-tag">Provider Bridge</span>
2079
+ </div>
2080
+ <p class="cmd-desc" data-i18n="cmd4Desc">
2081
+ สลับผู้ให้บริการ AI แบบทันที รองรับ <code>lmstudio</code>, <code>vllm</code>, <code>ollama</code>, <code>openai</code>, <code>gemini</code>, <code>groq</code>, <code>deepseek</code>, <code>anthropic</code>, และ <code>openrouter</code> พร้อมระบบตรวจสอบ Endpoint Latency
2082
+ </p>
2083
+ </div>
2084
+
2085
+ <!-- CMD 5: /gpu & /system -->
2086
+ <div class="cmd-card">
2087
+ <div class="cmd-syntax-bar">
2088
+ <span class="cmd-syntax">/gpu [status] &bull; /system</span>
2089
+ <span class="cmd-tag">Hardware Telemetry</span>
2090
+ </div>
2091
+ <p class="cmd-desc" data-i18n="cmd5Desc">
2092
+ ตรวจสอบการใช้ VRAM แบบเรียลไทม์, อุณหภูมิ GPU, Bus Width, อัตราการรับส่ง PCIe และโครงสร้างคอร์ซีพียู SMT / Hyper-Threading
2093
+ </p>
2094
+ </div>
2095
+
2096
+ <!-- CMD 6: /eval -->
2097
+ <div class="cmd-card">
2098
+ <div class="cmd-syntax-bar">
2099
+ <span class="cmd-syntax">/eval [ui | dashboard | validate | quick | run | judge | compare]</span>
2100
+ <span class="cmd-tag">Benchmark Suite</span>
2101
+ </div>
2102
+ <p class="cmd-desc" data-i18n="cmd6Desc">
2103
+ เปิดระบบทดสอบประสิทธิภาพโมเดล 500 ข้อ (Frozen Benchmark), สั่งเปิด Eval Studio Web Dashboard (Port 3001), รันชุดทดสอบ Enterprise 7-Point Model Compatibility (<code>npm run eval:compat</code>) หรือรันประเมินความถูกต้องด้านความปลอดภัย
2104
+ </p>
2105
+ </div>
2106
+
2107
+ <!-- CMD 7: /vram -->
2108
+ <div class="cmd-card">
2109
+ <div class="cmd-syntax-bar">
2110
+ <span class="cmd-syntax">/vram [check &lt;model&gt; | live | compare | ctx | tier] [--ctx &lt;len&gt;] [--quant &lt;type&gt;]</span>
2111
+ <span class="cmd-tag">Memory Predictor</span>
2112
+ </div>
2113
+ <p class="cmd-desc" data-i18n="cmd7Desc">
2114
+ คำนวณงบประมาณ VRAM ล่วงหน้าก่อนโหลดโมเดล แสดงตารางเปรียบเทียบขนาด KV Cache ตามความยาว Context และตรวจสอบว่าโมเดลจะฟิตลงในการ์ดจอหรือไม่
2115
+ </p>
2116
+ </div>
2117
+
2118
+ <!-- CMD 8: /mcp -->
2119
+ <div class="cmd-card">
2120
+ <div class="cmd-syntax-bar">
2121
+ <span class="cmd-syntax">/mcp [status | list | connect &lt;name&gt; &lt;url|cmd&gt; | tools | reload]</span>
2122
+ <span class="cmd-tag">Protocol Bridge</span>
2123
+ </div>
2124
+ <p class="cmd-desc" data-i18n="cmd8Desc">
2125
+ เชื่อมต่อไปยังเซิร์ฟเวอร์ Model Context Protocol (MCP) ภายนอก และควบคุม MCP Server ภายในระบบ (Streamable HTTP <code>POST /mcp</code>, Protocol 2025-11-25) รองรับการเชื่อมต่อจาก 10 ค่าย AI &amp; IDEs (Claude Desktop, Cursor, Windsurf, VS Code, AGY, Cline, Claude Code, Gemini CLI, LibreChat, OpenCode)
2126
+ </p>
2127
+ </div>
2128
+
2129
+ <!-- CMD 9: /stats & /thinking -->
2130
+ <div class="cmd-card">
2131
+ <div class="cmd-syntax-bar">
2132
+ <span class="cmd-syntax">/stats [overview | tokens] &bull; /thinking [show | hide | toggle]</span>
2133
+ <span class="cmd-tag">Diagnostics</span>
2134
+ </div>
2135
+ <p class="cmd-desc" data-i18n="cmd9Desc">
2136
+ แสดงความเร็วการสร้างโทเค็น (Prompt Tokens/s vs Eval Tokens/s) และสลับการแสดงผลกล่องความคิดภายใน (&lt;think&gt; / Thoughts) ของโมเดล Reasoning
2137
+ </p>
2138
+ </div>
2139
+ </div>
2140
+ </div>
2141
+
2142
+ <!-- SUB-SECTION 6.2 -->
2143
+ <div class="sub-section" id="params-load">
2144
+ <h3 class="sub-title">
2145
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect width="20" height="14" x="2" y="5" rx="2"/><line x1="2" y1="10" x2="22" y2="10"/></svg>
2146
+ <span data-i18n="sec62Title">6.2 ตารางการปรับแต่งการโหลดโมเดลเข้า VRAM (Model Load Parameters)</span>
2147
+ </h3>
2148
+ <p class="doc-p" data-i18n="sec62P">
2149
+ พารามิเตอร์ทั้งหมดในส่วนนี้ใช้ส่งผ่านคำสั่ง <code>lms load</code> หรือผ่าน REST API <code>POST /api/engine/load</code> เพื่อควบคุมพฤติกรรมในระดับไดรเวอร์และเคอร์เนล CUDA:
2150
+ </p>
2151
+
2152
+ <div class="param-grid">
2153
+ <!-- PARAM 1: contextLength -->
2154
+ <div class="param-card">
2155
+ <div class="param-header">
2156
+ <span class="param-name">contextLength</span>
2157
+ <div class="param-badges">
2158
+ <span class="badge-type">Integer</span>
2159
+ <span class="badge-impact-high">High VRAM Impact</span>
2160
+ </div>
2161
+ </div>
2162
+ <p class="param-desc" data-i18n="paramCtxDesc">
2163
+ กำหนดขนาดความยาวหน้าต่างบริบท (Context Window) มีผลต่อขนาดหน่วยความจำ KV Cache โดยตรง ยิ่งกำหนดสูง ยิ่งต้องใช้ VRAM มากขึ้น
2164
+ </p>
2165
+ <div class="param-meta-row">
2166
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">32768 (32K)</strong></span>
2167
+ <span>ขอบเขต: <strong class="param-meta-val">512 &ndash; 131072</strong></span>
2168
+ </div>
2169
+ </div>
2170
+
2171
+ <!-- PARAM 2: gpuOffload -->
2172
+ <div class="param-card">
2173
+ <div class="param-header">
2174
+ <span class="param-name">gpuOffload</span>
2175
+ <div class="param-badges">
2176
+ <span class="badge-type">String / Float</span>
2177
+ <span class="badge-impact-high">Critical Speed</span>
2178
+ </div>
2179
+ </div>
2180
+ <p class="param-desc" data-i18n="paramGpuDesc">
2181
+ สัดส่วนการส่งชั้นเลเยอร์ของโมเดลเข้าการ์ดจอ <code>max</code> คือนำเข้า VRAM ทั้งหมด, <code>off</code> คือรันบน CPU ทั้งหมด หรือระบุเป็นทศนิยม <code>0.0 &ndash; 1.0</code>
2182
+ </p>
2183
+ <div class="param-meta-row">
2184
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">max (100%)</strong></span>
2185
+ <span>ตัวเลือก: <strong class="param-meta-val">max, off, 0.0-1.0</strong></span>
2186
+ </div>
2187
+ </div>
2188
+
2189
+ <!-- PARAM 3: htMode -->
2190
+ <div class="param-card">
2191
+ <div class="param-header">
2192
+ <span class="param-name">htMode</span>
2193
+ <div class="param-badges">
2194
+ <span class="badge-type">Enum</span>
2195
+ <span class="badge-impact-high">+10%–25% Speed</span>
2196
+ </div>
2197
+ </div>
2198
+ <p class="param-desc" data-i18n="paramHtDesc">
2199
+ ควบคุมการจัดสรรเธรดซีพียูตามโครงสร้าง Hyper-Threading/SMT โหมด <code>physical</code> ช่วยปิดการแย่งแคช L1/L2 ให้ความเร็วสร้างโทเค็นสูงสุด
2200
+ </p>
2201
+ <div class="param-meta-row">
2202
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">physical</strong></span>
2203
+ <span>ตัวเลือก: <strong class="param-meta-val">physical, smt, auto, custom</strong></span>
2204
+ </div>
2205
+ </div>
2206
+
2207
+ <!-- PARAM 4: flashAttn -->
2208
+ <div class="param-card">
2209
+ <div class="param-header">
2210
+ <span class="param-name">flashAttn</span>
2211
+ <div class="param-badges">
2212
+ <span class="badge-type">Boolean</span>
2213
+ <span class="badge-impact-high">-30% VRAM</span>
2214
+ </div>
2215
+ </div>
2216
+ <p class="param-desc" data-i18n="paramFlashDesc">
2217
+ เปิดใช้เคอร์เนล FlashAttention-2 คำนวณ Attention Matrix แบบ Tiled บน SRAM ความเร็วสูง ลดความซับซ้อนหน่วยความจำจาก O(N&sup2;) เหลือ O(N)
2218
+ </p>
2219
+ <div class="param-meta-row">
2220
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">true (เปิด)</strong></span>
2221
+ <span>ตัวเลือก: <strong class="param-meta-val">true, false</strong></span>
2222
+ </div>
2223
+ </div>
2224
+
2225
+ <!-- PARAM 5: batchSize & ubatchSize -->
2226
+ <div class="param-card">
2227
+ <div class="param-header">
2228
+ <span class="param-name">batchSize / ubatchSize</span>
2229
+ <div class="param-badges">
2230
+ <span class="badge-type">Integer</span>
2231
+ <span class="badge-impact-med">VRAM Spike Control</span>
2232
+ </div>
2233
+ </div>
2234
+ <p class="param-desc" data-i18n="paramBatchDesc">
2235
+ <code>batchSize</code> ควบคุมการหั่นชิ้นประโยค Prompt ในระดับตรรกะ ส่วน <code>ubatchSize</code> ควบคุมขนาดสไลซ์ที่ส่งเข้าคำนวณใน CUDA Kernel ป้องกันอาการ VRAM พุ่งกระฉูดขณะอ่านคำถามยาว
2236
+ </p>
2237
+ <div class="param-meta-row">
2238
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">512 / 128</strong></span>
2239
+ <span>ขอบเขต: <strong class="param-meta-val">32 &ndash; 2048</strong></span>
2240
+ </div>
2241
+ </div>
2242
+
2243
+ <!-- PARAM 6: splitMode & tensorSplit -->
2244
+ <div class="param-card">
2245
+ <div class="param-header">
2246
+ <span class="param-name">splitMode / tensorSplit</span>
2247
+ <div class="param-badges">
2248
+ <span class="badge-type">Enum / String</span>
2249
+ <span class="badge-impact-med">Multi-GPU Only</span>
2250
+ </div>
2251
+ </div>
2252
+ <p class="param-desc" data-i18n="paramSplitDesc">
2253
+ วิธีกระจายน้ำหนักโมเดลข้ามการ์ดจอหลายใบ <code>layer</code> สำหรับการ์ดจอขนาด VRAM ต่างกัน, <code>row</code> สำหรับการ์ดรุ่นเดียวกันที่มีบริดจ์ความเร็วสูง
2254
+ </p>
2255
+ <div class="param-meta-row">
2256
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">layer</strong></span>
2257
+ <span>ตัวอย่าง: <strong class="param-meta-val">--tensor-split 20,12</strong></span>
2258
+ </div>
2259
+ </div>
2260
+
2261
+ <!-- PARAM 7: kvQuant -->
2262
+ <div class="param-card">
2263
+ <div class="param-header">
2264
+ <span class="param-name">kvQuant (ctk / ctv)</span>
2265
+ <div class="param-badges">
2266
+ <span class="badge-type">Enum</span>
2267
+ <span class="badge-impact-high">-50% to -70% VRAM</span>
2268
+ </div>
2269
+ </div>
2270
+ <p class="param-desc" data-i18n="paramKvDesc">
2271
+ บีบอัด Key และ Value ในหน่วยความจำบันทึกบทสนทนา โหมด <code>q8_0</code> ช่วยประหยัด VRAM ได้ 50% โดยสูญเสียความแม่นยำเพียง 0.2%
2272
+ </p>
2273
+ <div class="param-meta-row">
2274
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">q8_0</strong></span>
2275
+ <span>ตัวเลือก: <strong class="param-meta-val">fp16, q8_0, q4_0, q4_1</strong></span>
2276
+ </div>
2277
+ </div>
2278
+ </div>
2279
+ </div>
2280
+
2281
+ <!-- SUB-SECTION 6.3 -->
2282
+ <div class="sub-section" id="params-sampling">
2283
+ <h3 class="sub-title">
2284
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="m10 15 5-3-5-3v6Z"/></svg>
2285
+ <span data-i18n="sec63Title">6.3 การปรับแต่งการสุ่มคำตอบ (Inference Sampling Hyperparameters)</span>
2286
+ </h3>
2287
+ <p class="doc-p" data-i18n="sec63P">
2288
+ พารามิเตอร์การประมวลผลคำตอบ (Logit Post-Processing &amp; Sampling) ซึ่งส่งผลต่อความแม่นยำ ความสร้างสรรค์ และการป้องกันคำตอบวนลูป:
2289
+ </p>
2290
+
2291
+ <div class="param-grid">
2292
+ <!-- SAMPLING 1: Temperature -->
2293
+ <div class="param-card">
2294
+ <div class="param-header">
2295
+ <span class="param-name">temperature</span>
2296
+ <div class="param-badges">
2297
+ <span class="badge-type">Float</span>
2298
+ <span class="badge-impact-high">Creativity &amp; Logic</span>
2299
+ </div>
2300
+ </div>
2301
+ <p class="param-desc" data-i18n="paramTempDesc">
2302
+ ตัวปรับสเกลความน่าจะเป็นก่อนเข้า Softmax: $P(x_i) = \frac{\exp(z_i / T)}{\sum \exp(z_j / T)}$ สำหรับ ReAct Agent และงานเรียกใช้ Tools แนะนำ <strong>0.2 &ndash; 0.3</strong> เพื่อความแม่นยำสูงสุด, ค่า <strong>0.0</strong> สำหรับการทดสอบ Deterministic Benchmarking
2303
+ </p>
2304
+ <div class="param-meta-row">
2305
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">0.30</strong></span>
2306
+ <span>ขอบเขต: <strong class="param-meta-val">0.00 &ndash; 2.00</strong></span>
2307
+ </div>
2308
+ </div>
2309
+
2310
+ <!-- SAMPLING 2: min_p -->
2311
+ <div class="param-card">
2312
+ <div class="param-header">
2313
+ <span class="param-name">min_p (Minimum Probability)</span>
2314
+ <div class="param-badges">
2315
+ <span class="badge-type">Float</span>
2316
+ <span class="badge-impact-high">Modern Sampler</span>
2317
+ </div>
2318
+ </div>
2319
+ <p class="param-desc" data-i18n="paramMinpDesc">
2320
+ ตัดโทเค็นที่มีความน่าจะเป็นต่ำกว่าเกณฑ์สัมพัทธ์ $P_i &lt; min\_p \times P_{max}$ ทำงานได้ดีกว่า <code>top_p</code> แบบเดิมสำหรับโมเดลตระกูล Gemma 4 อย่างเห็นได้ชัด เพราะปรับตัวตามความมั่นใจของโมเดลได้แบบไดนามิก
2321
+ </p>
2322
+ <div class="param-meta-row">
2323
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">0.08</strong></span>
2324
+ <span>ขอบเขต: <strong class="param-meta-val">0.01 &ndash; 1.00</strong></span>
2325
+ </div>
2326
+ </div>
2327
+
2328
+ <!-- SAMPLING 3: top_p -->
2329
+ <div class="param-card">
2330
+ <div class="param-header">
2331
+ <span class="param-name">top_p (Nucleus Sampling)</span>
2332
+ <div class="param-badges">
2333
+ <span class="badge-type">Float</span>
2334
+ <span class="badge-impact-med">Cumulative Cutoff</span>
2335
+ </div>
2336
+ </div>
2337
+ <p class="param-desc" data-i18n="paramToppDesc">
2338
+ คัดเฉพาะกลุ่มโทเค็นที่มีผลรวมความน่าจะเป็นสะสมไม่เกินค่าที่กำหนด $\sum P_i \le top\_p$ ในระบบ Kiku หากเปิดใช้งาน <code>min_p</code> ระบบจะปลดล็อค <code>top_p = 1.0</code> โดยอัตโนมัติเพื่อไม่ให้ขัดขวางการทำงานของ Min-P
2339
+ </p>
2340
+ <div class="param-meta-row">
2341
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">1.0 (Auto)</strong></span>
2342
+ <span>ขอบเขต: <strong class="param-meta-val">0.01 &ndash; 1.00</strong></span>
2343
+ </div>
2344
+ </div>
2345
+
2346
+ <!-- SAMPLING 4: repeatPenalty -->
2347
+ <div class="param-card">
2348
+ <div class="param-header">
2349
+ <span class="param-name">repeatPenalty (repetition_penalty)</span>
2350
+ <div class="param-badges">
2351
+ <span class="badge-type">Float</span>
2352
+ <span class="badge-impact-med">Anti-Loop</span>
2353
+ </div>
2354
+ </div>
2355
+ <p class="param-desc" data-i18n="paramRepeatDesc">
2356
+ ลดทอนค่า Logit ของโทเค็นที่เคยปรากฏในข้อความที่สร้างไปแล้ว ช่วยขจัดปัญหาโมเดลตอบวนซ้ำประโยคเดิม แต่ไม่ควรตั้งเกิน 1.25 เพราะจะทำให้โมเดลปฏิเสธการใช้คำศัพท์ไวยากรณ์ที่จำเป็น
2357
+ </p>
2358
+ <div class="param-meta-row">
2359
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">1.10</strong></span>
2360
+ <span>ขอบเขต: <strong class="param-meta-val">1.00 &ndash; 1.50</strong></span>
2361
+ </div>
2362
+ </div>
2363
+
2364
+ <!-- SAMPLING 5: maxTokens -->
2365
+ <div class="param-card">
2366
+ <div class="param-header">
2367
+ <span class="param-name">maxTokens (max_tokens)</span>
2368
+ <div class="param-badges">
2369
+ <span class="badge-type">Integer</span>
2370
+ <span class="badge-impact-low">Output Ceiling</span>
2371
+ </div>
2372
+ </div>
2373
+ <p class="param-desc" data-i18n="paramTokensDesc">
2374
+ จำนวนโทเค็นสูงสุดที่โมเดลสามารถสร้างได้ในคำตอบเดียว ระบบได้สำรองพื้นที่บริบทสำหรับการตอบข้อยาว (Generation Reserve Buffer) ไว้ 8,192 โทเค็นเสมอ
2375
+ </p>
2376
+ <div class="param-meta-row">
2377
+ <span>ค่ามาตรฐาน: <strong class="param-meta-val">8192</strong></span>
2378
+ <span>ขอบเขต: <strong class="param-meta-val">256 &ndash; 32768</strong></span>
2379
+ </div>
2380
+ </div>
2381
+ </div>
2382
+ </div>
2383
+
2384
+ <!-- SUB-SECTION 6.4 -->
2385
+ <div class="sub-section" id="api-reference">
2386
+ <h3 class="sub-title">
2387
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m18 16 4-4-4-4"/><path d="m6 8-4 4 4 4"/><path d="m14.5 4-5 16"/></svg>
2388
+ <span data-i18n="sec64Title">6.4 REST API Reference &amp; Code Playbook</span>
2389
+ </h3>
2390
+ <p class="doc-p" data-i18n="sec64P">
2391
+ ตัวอย่างคำสั่ง cURL และโค้ด Node.js สำหรับนำไปเชื่อมต่อควบคุมการทำงานของ Inference Control Center แบบโปรแกรม:
2392
+ </p>
2393
+
2394
+ <!-- API 1: Hardware Telemetry -->
2395
+ <p style="font-size:13.5px; font-weight:700; color:var(--text-main); margin-bottom:6px;" data-i18n="sec64Api1Title">1. ตรวจสอบ Telemetry ฮาร์ดแวร์ (GPU, VRAM และ CPU SMT)</p>
2396
+ <div class="code-block">
2397
+ <div class="code-header">
2398
+ <span>GET /api/v1/system/hardware</span>
2399
+ <button type="button" class="btn-copy" onclick="copyCode(this)">Copy</button>
2400
+ </div>
2401
+ <pre><code># เรียกดูข้อมูลการ์ดจอและโครงสร้างซีพียู
2402
+ curl -s http://localhost:3002/api/v1/system/hardware | jq .data
2403
+
2404
+ # ตัวอย่าง Response:
2405
+ # {
2406
+ # "gpu": { "name": "NVIDIA GeForce RTX 2060", "vramTotalMb": 6144, "vramFreeMb": 4200, "temperatureC": 52 },
2407
+ # "cpu": { "model": "AMD Ryzen 5 3600", "physicalCores": 6, "logicalCores": 12, "smtActive": true, "recommendedThreads": 6 }
2408
+ # }</code></pre>
2409
+ </div>
2410
+
2411
+ <!-- API 2: Load Model -->
2412
+ <p style="font-size:13.5px; font-weight:700; color:var(--text-main); margin-bottom:6px; margin-top:20px;" data-i18n="sec64Api2Title">2. สั่งโหลดโมเดลเข้า VRAM พร้อมกำหนด Hyper-Threading และ FlashAttention</p>
2413
+ <div class="code-block">
2414
+ <div class="code-header">
2415
+ <span>POST /api/engine/load</span>
2416
+ <button type="button" class="btn-copy" onclick="copyCode(this)">Copy</button>
2417
+ </div>
2418
+ <pre><code># ยิงคำสั่งให้ LM Studio โหลดโมเดลพร้อมตั้งค่าความยาว Context 32K
2419
+ curl -X POST http://localhost:3002/api/engine/load \
2420
+ -H "Content-Type: application/json" \
2421
+ -d '{
2422
+ "engine": "lms",
2423
+ "model": "google/gemma-4-e4b",
2424
+ "gpuOffload": "max",
2425
+ "cpuThreads": 6,
2426
+ "htMode": "physical",
2427
+ "contextLength": 32768,
2428
+ "flashAttn": true,
2429
+ "batchSize": 512,
2430
+ "ubatchSize": 128
2431
+ }'</code></pre>
2432
+ </div>
2433
+
2434
+ <!-- API 3: Node.js Snippet -->
2435
+ <p style="font-size:13.5px; font-weight:700; color:var(--text-main); margin-bottom:6px; margin-top:20px;" data-i18n="sec64Api3Title">3. ตัวอย่างการเขียนสคริปต์ Node.js สำหรับสั่งโหลดโมเดลอัตโนมัติ</p>
2436
+ <div class="code-block">
2437
+ <div class="code-header">
2438
+ <span>Node.js ESM Script</span>
2439
+ <button type="button" class="btn-copy" onclick="copyCode(this)">Copy</button>
2440
+ </div>
2441
+ <pre><code>import fetch from 'node:fetch';
2442
+
2443
+ async function configureInferenceEngine() {
2444
+ const payload = {
2445
+ engine: 'lms',
2446
+ model: 'google/gemma-4-e4b',
2447
+ gpuOffload: 'max',
2448
+ htMode: 'physical',
2449
+ contextLength: 32768,
2450
+ flashAttn: true
2451
+ };
2452
+
2453
+ const res = await fetch('http://localhost:3002/api/engine/load', {
2454
+ method: 'POST',
2455
+ headers: { 'Content-Type': 'application/json' },
2456
+ body: JSON.stringify(payload)
2457
+ });
2458
+
2459
+ const result = await res.json();
2460
+ console.log('Engine status:', result.ok ? 'Ready' : result.error);
2461
+ }
2462
+
2463
+ configureInferenceEngine();</code></pre>
2464
+ </div>
2465
+
2466
+ <!-- API 4: Unload Model -->
2467
+ <p style="font-size:13.5px; font-weight:700; color:var(--text-main); margin-bottom:6px; margin-top:20px;" data-i18n="sec64Api4Title">4. สั่งปล่อยคืน VRAM ทั้งหมด (Unload Model)</p>
2468
+ <div class="code-block">
2469
+ <div class="code-header">
2470
+ <span>POST /api/engine/unload</span>
2471
+ <button type="button" class="btn-copy" onclick="copyCode(this)">Copy</button>
2472
+ </div>
2473
+ <pre><code>curl -X POST http://localhost:3002/api/engine/unload \
2474
+ -H "Content-Type: application/json" \
2475
+ -d '{"engine": "lms", "model": "google/gemma-4-e4b"}'</code></pre>
2476
+ </div>
2477
+ </div>
2478
+ </section>
2479
+
2480
+ <!-- CHAPTER 7: Tuning Playbook & OOM -->
2481
+ <section class="doc-section" id="section-tuning">
2482
+ <div class="doc-section-header">
2483
+ <div class="section-icon-badge badge-amber">
2484
+ <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg>
2485
+ </div>
2486
+ <div>
2487
+ <h2 class="doc-section-title" data-i18n="sec7Title">7. คู่มือการปรับจูนและแก้ปัญหา (Tuning Playbook &amp; OOM)</h2>
2488
+ <p class="doc-section-desc" data-i18n="sec7Sub">ตารางการปรับแต่งตามสเปก VRAM, ขั้นตอนกู้วิกฤต VRAM Overflow และข้อควรระวัง PCIe Bus</p>
2489
+ </div>
2490
+ </div>
2491
+
2492
+ <!-- SUB-SECTION 7.1 -->
2493
+ <div class="sub-section" id="tuning-tiers" style="margin-top:0; border-top:none; padding-top:0;">
2494
+ <h3 class="sub-title">
2495
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 3v12"/><circle cx="18" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/></svg>
2496
+ <span data-i18n="sec71Title">7.1 Hardware VRAM Tiers Matrix</span>
2497
+ </h3>
2498
+ <p class="doc-p" data-i18n="sec71P">
2499
+ การปรับแต่งที่เหมาะสมที่สุดตามความจุการ์ดจอ เพื่อให้ได้ความเร็วในการสร้างโทเค็นสูงสุดและไม่เกิดอาการหน่วยความจำล้น:
2500
+ </p>
2501
+
2502
+ <div class="table-container">
2503
+ <table class="doc-table">
2504
+ <thead>
2505
+ <tr>
2506
+ <th data-i18n="sec71Th1">VRAM Capacity</th>
2507
+ <th data-i18n="sec71Th2">โมเดลและ Quantization แนะนำ</th>
2508
+ <th data-i18n="sec71Th3">Context &amp; KV Settings</th>
2509
+ <th data-i18n="sec71Th4">CPU SMT Mode</th>
2510
+ </tr>
2511
+ </thead>
2512
+ <tbody>
2513
+ <tr>
2514
+ <td><strong>6 GB VRAM</strong><br>(GTX 1660 / RTX 2060)</td>
2515
+ <td>Gemma 4 E4B (<code>Q4_K_M</code>)</td>
2516
+ <td data-i18n="sec71R1C3">Context <strong>16,384</strong> (16K), KV Cache: <code>q4_0</code>, FlashAttn: เปิด</td>
2517
+ <td><code>physical</code></td>
2518
+ </tr>
2519
+ <tr>
2520
+ <td><strong>8 GB VRAM</strong><br>(RTX 3070 / RTX 4060)</td>
2521
+ <td>Gemma 4 E4B (<code>Q4_K_M</code> หรือ <code>Q5_K_M</code>)</td>
2522
+ <td data-i18n="sec71R2C3">Context <strong>32,768</strong> (32K), KV Cache: <code>q8_0</code>, FlashAttn: เปิด</td>
2523
+ <td><code>physical</code></td>
2524
+ </tr>
2525
+ <tr>
2526
+ <td><strong>12 – 16 GB VRAM</strong><br>(RTX 4070 / RTX 4080)</td>
2527
+ <td>Gemma 4 E4B (<code>Q8_0</code>) หรือ Qwen 2.5 14B (<code>Q4_K_M</code>)</td>
2528
+ <td data-i18n="sec71R3C3">Context <strong>32,768 &ndash; 65,536</strong>, KV Cache: <code>q8_0</code> หรือ <code>fp16</code></td>
2529
+ <td><code>physical</code> / <code>auto</code></td>
2530
+ </tr>
2531
+ <tr>
2532
+ <td><strong>24 GB+ / Multi-GPU</strong><br>(RTX 3090 / 4090 / 2x GPUs)</td>
2533
+ <td>Qwen 2.5 32B (<code>Q4_K_M</code>) หรือ LLaMA 3.3 70B</td>
2534
+ <td data-i18n="sec71R4C3">Context <strong>65,536+</strong>, Multi-GPU Split: <code>layer</code> หรือ <code>row</code></td>
2535
+ <td><code>smt</code> / <code>all</code></td>
2536
+ </tr>
2537
+ </tbody>
2538
+ </table>
2539
+ </div>
2540
+ </div>
2541
+
2542
+ <!-- SUB-SECTION 7.2 -->
2543
+ <div class="sub-section" id="tuning-oom">
2544
+ <h3 class="sub-title">
2545
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
2546
+ <span data-i18n="sec72Title">7.2 4-Step Deterministic Out-Of-Memory (OOM) Recovery</span>
2547
+ </h3>
2548
+ <p class="doc-p" data-i18n="sec72P">
2549
+ หากแถบวัด VRAM ในหน้า Settings แสดงสถานะสีแดงเกิน 90% หรือไดรเวอร์เกิดข้อผิดพลาด <code>CUDA Out of Memory (exit code 1)</code> ให้ปฏิบัติตามลำดับ 4 ขั้นตอนนี้เพื่อกู้คืนระบบโดยไม่ต้องรีบูตเครื่อง:
2550
+ </p>
2551
+
2552
+ <div class="doc-callout callout-tip">
2553
+ <div class="callout-icon">
2554
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>
2555
+ </div>
2556
+ <div data-i18n="sec72Step1">
2557
+ <strong>ขั้นตอนที่ 1: บีบอัด KV Cache เป็น <code>q8_0</code> หรือ <code>q4_0</code></strong>
2558
+ <br>ส่งผลให้ขนาด KV Cache ลดลงทันที 47% ถึง 72% ช่วยคืนพื้นที่ VRAM กลับมาได้ทันที 1.2 ถึง 2.5 GB โดยไม่จำเป็นต้องลดความยาว Context
2559
+ </div>
2560
+ </div>
2561
+
2562
+ <div class="doc-callout callout-tip">
2563
+ <div class="callout-icon">
2564
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>
2565
+ </div>
2566
+ <div data-i18n="sec72Step2">
2567
+ <strong>ขั้นตอนที่ 2: ปรับลดความยาว Context Length ลงหนึ่งสเต็ป</strong>
2568
+ <br>หากเดิมตั้งไว้ 32,768 ให้ปรับลดลงมาที่ 16,384 (16K) หรือ 8,192 (8K) ซึ่งเพียงพอสำหรับงานสนทนาและค้นคว้าทั่วไปถึง 95%
2569
+ </div>
2570
+ </div>
2571
+
2572
+ <div class="doc-callout callout-tip">
2573
+ <div class="callout-icon">
2574
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>
2575
+ </div>
2576
+ <div data-i18n="sec72Step3">
2577
+ <strong>ขั้นตอนที่ 3: ตรวจสอบและเปิดใช้งาน <code>flashAttn = true</code></strong>
2578
+ <br>ยืนยันว่าการ์ดจอรองรับ FlashAttention-2 เพื่อหลีกเลี่ยงการจัดสรร Memory Matrix ขนาดใหญ่ขณะทำ Prompt Prefill
2579
+ </div>
2580
+ </div>
2581
+
2582
+ <div class="doc-callout callout-tip">
2583
+ <div class="callout-icon">
2584
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>
2585
+ </div>
2586
+ <div data-i18n="sec72Step4">
2587
+ <strong>ขั้นตอนที่ 4: ปรับสัดส่วน <code>gpuOffload</code> เป็นทศนิยม (เช่น <code>0.85</code>)</strong>
2588
+ <br>สั่งให้ระบบแบ่งชั้นเลเยอร์ 15% ท้ายสุดไปรันบน System RAM แทนการบังคับยัดลงการ์ดจอทั้งหมด
2589
+ </div>
2590
+ </div>
2591
+ </div>
2592
+
2593
+ <!-- SUB-SECTION 7.3 -->
2594
+ <div class="sub-section" id="tuning-pcie">
2595
+ <h3 class="sub-title">
2596
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="2" width="20" height="8" rx="2" ry="2"/><rect x="2" y="14" width="20" height="8" rx="2" ry="2"/><line x1="6" y1="6" x2="6.01" y2="6"/><line x1="6" y1="18" x2="6.01" y2="18"/></svg>
2597
+ <span data-i18n="sec73Title">7.3 PCIe Bandwidth &amp; Partial Offloading Warning</span>
2598
+ </h3>
2599
+ <p class="doc-p" data-i18n="sec73P">
2600
+ ข้อควรระวังสำคัญที่สุดในการตั้งค่า Partial Offload: ช่องเสียบ PCIe Gen3 x16 มีแบนด์วิดท์สูงสุดเพียง <strong>~15.75 GB/s</strong> (และ PCIe Gen3 x8 เพียง <strong>~7.8 GB/s</strong>) ซึ่งต่ำกว่า VRAM บนการ์ดจอ (360–1,000 GB/s) ถึง 25–60 เท่า!
2601
+ </p>
2602
+ <div class="doc-callout callout-warn">
2603
+ <div class="callout-icon">
2604
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
2605
+ </div>
2606
+ <div data-i18n="sec73Warn">
2607
+ <strong>คำเตือนเรื่องความเร็วร่วง (PCIe Thrashing):</strong> หากท่านปล่อยให้โมเดลล้นไปรันบน System RAM เพียง 2–3 เลเยอร์ ทุกๆ โทเค็นที่สร้างขึ้น ข้อมูลผลลัพธ์ระหว่างเลเยอร์จะต้องถูกส่งข้ามบัส PCIe สลับไปมาระหว่างการ์ดจอกับเมนบอร์ด ความเร็วการสร้างโทเค็นจะร่วงลงจาก 70 tokens/s เหลือเพียง <strong>8–12 tokens/s ทันที</strong> ดังนั้น ควรเลือกโมเดล Quantization ขนาดที่ <em>บรรจุลงใน VRAM ได้ 100%</em> เสมอเพื่อรักษาประสิทธิภาพสูงสุด
2608
+ </div>
2609
+ </div>
2610
+ </div>
2611
+ </section>
2612
+
2613
+ </main>
2614
+ </div>
2615
+
2616
+ <!-- Floating Back to Top Button for Mobile -->
2617
+ <button type="button" id="btn-scroll-top" class="btn-scroll-top" onclick="window.scrollTo({top:0,behavior:'smooth'})" aria-label="Scroll to top" title="กลับขึ้นด้านบน">
2618
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>
2619
+ </button>
2620
+
2621
+ <script>
2622
+ // Copy Code Utility
2623
+ function copyCode(btn) {
2624
+ const code = btn.closest('.code-block').querySelector('pre code').innerText;
2625
+ navigator.clipboard.writeText(code).then(() => {
2626
+ const orig = btn.textContent;
2627
+ btn.textContent = 'Copied!';
2628
+ btn.style.borderColor = 'var(--accent-emerald)';
2629
+ btn.style.color = 'var(--accent-emerald)';
2630
+ setTimeout(() => {
2631
+ btn.textContent = orig;
2632
+ btn.style.borderColor = '';
2633
+ btn.style.color = '';
2634
+ }, 1800);
2635
+ });
2636
+ }
2637
+
2638
+ // Sidebar highlight
2639
+ function highlightSidebar(el) {
2640
+ document.querySelectorAll('.sidebar-link').forEach(l => l.classList.remove('active'));
2641
+ document.querySelectorAll('.sidebar-sublink').forEach(l => l.classList.remove('active'));
2642
+ el.classList.add('active');
2643
+ if (window.innerWidth <= 960) {
2644
+ el.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' });
2645
+ }
2646
+ }
2647
+
2648
+ // Sublink highlight
2649
+ function highlightSublink(el) {
2650
+ document.querySelectorAll('.sidebar-sublink').forEach(l => l.classList.remove('active'));
2651
+ el.classList.add('active');
2652
+ const parentItem = el.closest('.sidebar-item');
2653
+ if (parentItem) {
2654
+ const parentLink = parentItem.querySelector('.sidebar-link');
2655
+ if (parentLink) {
2656
+ document.querySelectorAll('.sidebar-link').forEach(l => l.classList.remove('active'));
2657
+ parentLink.classList.add('active');
2658
+ if (window.innerWidth <= 960) {
2659
+ parentLink.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' });
2660
+ }
2661
+ }
2662
+ }
2663
+ }
2664
+
2665
+ // Mobile & Desktop ScrollSpy and Navigation Tracking
2666
+ function initScrollSpy() {
2667
+ const targets = document.querySelectorAll('.doc-section, .sub-section[id]');
2668
+ if (!('IntersectionObserver' in window) || !targets.length) return;
2669
+
2670
+ const observer = new IntersectionObserver((entries) => {
2671
+ entries.forEach(entry => {
2672
+ if (entry.isIntersecting) {
2673
+ const id = entry.target.getAttribute('id');
2674
+ if (entry.target.classList.contains('sub-section')) {
2675
+ const sublink = document.querySelector('.sidebar-sublink[href="#' + id + '"]');
2676
+ if (sublink) {
2677
+ document.querySelectorAll('.sidebar-sublink').forEach(l => l.classList.remove('active'));
2678
+ sublink.classList.add('active');
2679
+ const parentItem = sublink.closest('.sidebar-item');
2680
+ if (parentItem) {
2681
+ const parentLink = parentItem.querySelector('.sidebar-link');
2682
+ if (parentLink) {
2683
+ document.querySelectorAll('.sidebar-link').forEach(l => l.classList.remove('active'));
2684
+ parentLink.classList.add('active');
2685
+ if (window.innerWidth <= 960) {
2686
+ parentLink.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' });
2687
+ }
2688
+ }
2689
+ }
2690
+ }
2691
+ } else if (entry.target.classList.contains('doc-section')) {
2692
+ const link = document.querySelector('.sidebar-link[href="#' + id + '"]');
2693
+ if (link) {
2694
+ document.querySelectorAll('.sidebar-link').forEach(l => l.classList.remove('active'));
2695
+ link.classList.add('active');
2696
+ if (window.innerWidth <= 960) {
2697
+ link.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' });
2698
+ }
2699
+ }
2700
+ }
2701
+ }
2702
+ });
2703
+ }, {
2704
+ rootMargin: '-15% 0px -70% 0px',
2705
+ threshold: 0
2706
+ });
2707
+
2708
+ targets.forEach(s => observer.observe(s));
2709
+ }
2710
+
2711
+ // Floating Back to Top Handler
2712
+ function initScrollTop() {
2713
+ const btn = document.getElementById('btn-scroll-top');
2714
+ if (!btn) return;
2715
+ window.addEventListener('scroll', () => {
2716
+ if (window.scrollY > 280) {
2717
+ btn.classList.add('visible');
2718
+ } else {
2719
+ btn.classList.remove('visible');
2720
+ }
2721
+ }, { passive: true });
2722
+ }
2723
+
2724
+ // Theme Toggle
2725
+ function toggleTheme() {
2726
+ const current = document.documentElement.getAttribute('data-theme') || 'dark';
2727
+ const next = current === 'dark' ? 'light' : 'dark';
2728
+ document.documentElement.setAttribute('data-theme', next);
2729
+ localStorage.setItem('kiku_theme', next);
2730
+ }
2731
+
2732
+ // Language Toggle & Complete i18n Engine
2733
+ const DOCS_I18N = {
2734
+ th: {
2735
+ navBackSettings: 'Inference Controls',
2736
+ navBackChat: 'Chat',
2737
+ tocHeading: 'สารบัญเนื้อหา (Contents)',
2738
+ tocArch: '1. สถาปัตยกรรมระบบ',
2739
+ tocArch1: '1.1 3-Tier Suite Topology',
2740
+ tocArch2: '1.2 ReAct & Compaction',
2741
+ tocArch3: '1.3 Atomic Persistence',
2742
+ tocEngines: '2. LM Studio vs vLLM',
2743
+ tocEngines1: '2.1 Unified Memory vs PagedAttn',
2744
+ tocEngines2: '2.2 GGUF Quantization Scales',
2745
+ tocEngines3: '2.3 CLI Flag Matrix',
2746
+ tocCpuHt: '3. CPU Hyper-Threading / SMT',
2747
+ tocCpu1: '3.1 Bandwidth Bottleneck',
2748
+ tocCpu2: '3.2 SMT Cache Thrashing',
2749
+ tocCpu3: '3.3 The 4 htMode Settings',
2750
+ tocVram: '4. VRAM Footprint & Multi-GPU',
2751
+ tocVram1: '4.1 Weight Memory Equation',
2752
+ tocVram2: '4.2 Hybrid KV Attention Math',
2753
+ tocVram3: '4.3 Activation & CUDA Overhead',
2754
+ tocVram4: '4.4 Tensor Split Heuristic',
2755
+ tocLan: '5. Zero-Key LAN Discovery',
2756
+ tocLan1: '5.1 Concurrency & Sweep Budget',
2757
+ tocLan2: '5.2 Probed Ports & Fingerprint',
2758
+ tocLan3: '5.3 SSRF & RFC1918 Guard',
2759
+ tocApi: '6. Model Tuning & Commands',
2760
+ tocApi1: '6.1 CLI & Slash Commands',
2761
+ tocApi2: '6.2 Load Parameter Matrix',
2762
+ tocApi3: '6.3 Sampling Hyperparameters',
2763
+ tocApi4: '6.4 REST API Code Playbook',
2764
+ tocTuning: '7. Tuning Playbook & OOM',
2765
+ tocTuning1: '7.1 Hardware VRAM Tiers',
2766
+ tocTuning2: '7.2 4-Step OOM Recovery',
2767
+ tocTuning3: '7.3 PCIe Bandwidth & Bus',
2768
+ heroBadge: 'Architecture & Engineering Manual',
2769
+ heroTitle: 'Inference Control Center Architecture',
2770
+ heroSubtitle: 'คู่มือเชิงลึกและสถาปัตยกรรมทางเทคนิคของศูนย์ควบคุมการประมวลผล AI การจัดสรรทรัพยากร VRAM โครงสร้างเธรด CPU SMT และระบบค้นหาเครื่องยนต์ Local AI ภายในเครือข่าย',
2771
+ hwBannerTitle: 'ระบบฮาร์ดแวร์ของคุณในปัจจุบัน (Live Telemetry)',
2772
+ hwBannerMeta: 'กำลังดึงข้อมูลเซ็นเซอร์จาก /api/v1/system/hardware...',
2773
+ sec1Title: '1. สถาปัตยกรรมระบบ (System Architecture & 3-Tier Data Flow)',
2774
+ sec1Sub: 'โครงสร้างการสื่อสารแบบแยกส่วน Process Isolation, วงรอบการตัดสินใจ ReAct Loop และระบบจัดการหน่วยความจำถาวร',
2775
+ sec1P: 'ระบบ Kiku Agent ถูกออกแบบบนรากฐานสถาปัตยกรรม <strong>3-Tier Modular Suite Architecture</strong> เพื่อแยกกระบวนการทำงานระหว่างการแสดงผลส่วนหน้า (Presentation), การควบคุมจัดการสถานะ (Orchestration & Web Server) และการคำนวณโครงข่ายประสาทเทียม (Neural Compute Engine) ออกจากกันอย่างเด็ดขาด ป้องกันไม่ให้การประมวลผลคำตอบที่ใช้ทรัพยากรสูงส่งผลกระทบต่อความลื่นไหลของ UI',
2776
+ sec11Title: '1.1 3-Tier Suite Topology & Process Isolation',
2777
+ sec11P: 'การทำงานของทั้ง 3 เลเยอร์เชื่อมต่อกันผ่านโปรโตคอลมาตรฐานที่ไร้การผูกขาด (Decoupled IPC & HTTP Transport):',
2778
+ tier1Desc: 'Vite + React 19 + Tailwind CSS 4 Single Page Application (SPA) บริการข้อมูลผลงาน ประวัติ และมัลติมีเดีย ปรับปรุงด้วย Liquid Glass Design System',
2779
+ tier2Desc: 'Node.js HTTP Server ทำหน้าที่เป็น API Gateway, บริการหน้าแชทหลัก, หน้าควบคุม Inference Control Center (/settings), หน้าคู่มือ (/docs), REST API Router และ Streamable HTTP Model Context Protocol (MCP) Server (/mcp)',
2780
+ archArrow: '&#11015; OpenAI-Compatible REST, Server-Sent Events (SSE) & Child Process IPC &#11015;',
2781
+ tier3aDesc: 'llama.cpp Engine รองรับ Cross-Platform ทั้ง Windows, macOS (Metal) และ Linux รองรับโมเดล GGUF Quantization ผ่าน lms CLI',
2782
+ tier3bDesc: 'Enterprise High-Throughput Engine ทำงานบน WSL2 / Linux พร้อมระบบจัดการ KV Cache เสมือน PagedAttention และ Continuous Batching',
2783
+ tier3cDesc: 'เชื่อมต่อตรงกับ API ภายนอก ได้แก่ Google Gemini, OpenAI, Groq, DeepSeek และ OpenRouter ผ่านคลาสตัวกลาง LLMClient',
2784
+ sec12Title: '1.2 ReAct Cognitive Loop & Context Compaction',
2785
+ sec12P: 'สมองกลของตัวแทน AI ทำงานด้วยวงรอบ <strong>ReAct (Reasoning + Acting)</strong> โดยใช้หลักการ <em>Dynamic Multi-Factor Score Ranking</em> ในการคัดเลือกเครื่องมือ (Tools) แทนการใช้โครงสร้าง <code>if/else</code> หรือคีย์เวิร์ดตายตัว:',
2786
+ sec12L1: '<strong>Tool Priority Scoring:</strong> เครื่องมือที่ตรงเงื่อนไขจะถูกประเมินคะแนนเชิงเส้น $Score = Explicit(+100) + Priority(+20) + Direct(+10) + RankScore(15 - 3i - r)$ พร้อมเพดานโควตาคลัสเตอร์เพื่อกระจายความหลากหลายของเครื่องมือ ไม่ผูกขาดกับหมวดใดหมวดหนึ่ง',
2787
+ sec12L2: '<strong>Context Compactor (<code>compactToolResultForContext</code>):</strong> ผลลัพธ์ดิบที่ส่งคืนจากเครื่องมือจะถูกกรองเอาลิงก์ตกแต่งและฟิลด์ฟุ่มเฟือยออก คงเหลือเฉพาะคีย์ข้อมูลสำคัญ เพื่อลดการสิ้นเปลือง Context Window และลดความหน่วง (Latency) ในการอ่านโทเค็นของ LLM',
2788
+ sec12L3: '<strong>4-Tier Context Allocation:</strong> จัดสรรพื้นที่บริบทอย่างเป็นระบบ — 20% สำหรับคำถามของผู้ใช้, 40% สำหรับสถานะและแผนงานในหน่วยความจำแอคทีฟ, 20% สำหรับบันทึกสะท้อนผลลัพธ์ระยะยาว (Reflections), และ 20% สำหรับเครื่องมือและการสนทนาทั่วไป',
2789
+ sec13Title: '1.3 Atomic Persistence Queue & Storage Guarantees',
2790
+ sec13P: 'สถานะการปรับแต่งเครื่องยนต์และการตั้งค่าอนุมานถูกจัดเก็บ 2 ระดับอย่างสมบูรณ์:',
2791
+ sec13Callout: '<strong>Atomic Write Pipeline:</strong> เมื่อมีการเปลี่ยนค่าในหน้าเว็บ ข้อมูลจะถูกบันทึกลง <code>localStorage</code> ฝั่งเบราว์เซอร์ทันทีเพื่อให้ UI ตอบสนองในระดับ 0ms และส่งสัญญาณต่อไปยังเซิร์ฟเวอร์เพื่อบันทึกลงไฟล์ <code>kiku_config.json</code> ผ่านฟังก์ชันคิว <code>withSettingsWriteQueue()</code> โดยเขียนลงไฟล์ชั่วคราว <code>kiku_config.json.tmp</code> ก่อนสลับชื่อไฟล์แบบอะตอมมิก เพื่อป้องกันไฟล์เสียหายกรณีเซิร์ฟเวอร์ดับกะทันหัน 100%',
2792
+
2793
+ sec2Title: '2. เปรียบเทียบเครื่องยนต์ประมวลผล (LM Studio vs vLLM)',
2794
+ sec2Sub: 'ความแตกต่างเชิงสถาปัตยกรรมลึก มาตราส่วน GGUF Quantization และตารางแม็ปพารามิเตอร์ 1:1',
2795
+ sec21Title: '2.1 llama.cpp Unified Memory vs vLLM PagedAttention',
2796
+ sec21P: 'ระบบรองรับทั้งเครื่องยนต์ระดับผู้ใช้ทั่วไป (Consumer Desktop) และเครื่องยนต์ระดับศูนย์ข้อมูล (Enterprise Serving) โดยทั้งสองมีหลักการจัดสรรหน่วยความจำที่แตกต่างกัน:',
2797
+ sec21Th1: 'คุณสมบัติเชิงวิศวกรรม',
2798
+ sec21Th2: 'LM Studio (llama.cpp)',
2799
+ sec21Th3: 'vLLM (PagedAttention)',
2800
+ sec21R1C1: 'Core Architecture',
2801
+ sec21R1C2: 'C/C++ CUDA, Metal, ROCm Kernels พร้อมตัวคูณเวกเตอร์ SIMD (AVX2/AVX-512)',
2802
+ sec21R1C3: 'Python/C++ Custom CUDA Kernels พัฒนาบนแนวคิด OS Virtual Memory Paging',
2803
+ sec21R2C1: 'ระบบปฏิบัติการที่รองรับ',
2804
+ sec21R2C2: 'Windows 10/11, macOS (Apple Silicon Metal), Linux',
2805
+ sec21R2C3: 'Linux Native หรือ Windows 11 ผ่าน WSL2 เท่านั้น (ไม่รองรับ Native Windows)',
2806
+ sec21R3C1: 'รูปแบบไฟล์โมเดล',
2807
+ sec21R3C2: 'GGUF Single-File Quantizations (Q4_K_M, Q6_K, Q8_0)',
2808
+ sec21R3C3: 'HuggingFace SafeTensors, AWQ, GPTQ, FP8 Checkpoints',
2809
+ sec21R4C1: 'KV Cache Allocation',
2810
+ sec21R4C2: 'จัดสรรบล็อกหน่วยความจำแบบต่อเนื่อง (Contiguous VRAM Buffer)',
2811
+ sec21R4C3: 'แบ่ง KV Cache เป็นเพจขนาดเล็ก (Paged Blocks) ลด Memory Fragmentation เหลือ &lt; 4%',
2812
+ sec21R5C1: 'Batching Strategy',
2813
+ sec21R5C2: 'Static / Dynamic Micro-batching (เน้น Single-stream Latency)',
2814
+ sec21R5C3: 'Continuous Batching (Iteration-level Scheduling) เพื่อรองรับผู้ใช้พร้อมกันจำนวนมาก',
2815
+ sec21R6C1: 'ฮาร์ดแวร์เป้าหมาย',
2816
+ sec21R6C2: 'การ์ดจอเดี่ยว 6GB, 8GB, 12GB หรือเครื่องไม่มีการ์ดจอ (CPU Offload)',
2817
+ sec21R6C3: 'Workstation หลายการ์ดจอ หรือ Data Center GPUs (RTX 4090, A100, H100)',
2818
+ sec22Title: '2.2 GGUF Quantization Scales & Bits Per Weight (BPW)',
2819
+ sec22P: 'GGUF ใช้วิธีการบีบอัดน้ำหนักโมเดลแบบ K-Quants ซึ่งใช้จำนวนบิตต่อค่าน้ำหนัก (Bits Per Weight - BPW) แตกต่างกันในแต่ละเลเยอร์ โดยพิจารณาจากความไวต่อการสูญเสียข้อมูล:',
2820
+ sec22Th1: 'ระดับ Quantization',
2821
+ sec22Th2: 'BPW แท้จริง',
2822
+ sec22Th3: 'ขนาดบน VRAM (8B Model)',
2823
+ sec22Th4: 'Perplexity Delta (&Delta;PPL)',
2824
+ sec22Th5: 'คำแนะนำการใช้งาน',
2825
+ sec22ChipRec: 'แนะนำ',
2826
+ sec22R1C5: 'คุ้มค่าสูงสุดสำหรับ GPU 6GB และ 8GB ให้ความเร็วและความแม่นยำสมดุลที่สุด',
2827
+ sec22R2C5: 'เหมาะสำหรับผู้ใช้ที่ต้องการคำตอบภาษาไทยและจีนที่สมบูรณ์ขึ้น บนการ์ด 8GB–12GB',
2828
+ sec22R3C5: 'คุณภาพเทียบเคียง FP16 เหมาะสำหรับการ์ดจอ 12GB ขึ้นไป เช่น RTX 4070',
2829
+ sec22R4C5: 'มาตรฐานสำหรับการประเมินผล Benchmarking และการคำนวณขั้นสูงบน GPU 16GB+',
2830
+ sec22R5C5: 'น้ำหนักดั้งเดิมก่อนควอนต์ ใช้สำหรับวิจัยหรือ Fine-tuning',
2831
+ sec23Title: '2.3 Flag Translation Matrix: LM Studio (lms) vs vLLM CLI',
2832
+ sec23P: 'ตารางเทียบเคียงคำสั่งพารามิเตอร์ 1:1 เพื่อให้นักพัฒนาสามารถสลับการควบคุมระหว่าง LM Studio และ vLLM ได้อย่างแม่นยำ:',
2833
+ sec23Th1: 'หน้าที่การควบคุม',
2834
+ sec23Th2: 'LM Studio (<code>lms load</code>)',
2835
+ sec23Th3: 'vLLM (<code>python -m vllm.entrypoints.openai.api_server</code>)',
2836
+ sec23R1C1: 'การดึงโมเดลเข้า VRAM',
2837
+ sec23R2C1: 'ความยาว Context Window',
2838
+ sec23R3C1: 'จำนวนคำขอพร้อมกัน (Slots)',
2839
+ sec23R4C1: 'Attention Acceleration',
2840
+ sec23R4C3: 'เปิดทำงานโดยอัตโนมัติ (หรือใช้ <code>--enforce-eager</code> เพื่อปิด)',
2841
+ sec23R5C1: 'การแบ่งโมเดลหลาย GPU',
2842
+ sec23R6C1: 'การบีบอัด KV Cache',
2843
+
2844
+ sec3Title: '3. การจัดการ CPU Hyper-Threading & SMT Topology',
2845
+ sec3Sub: 'หลักการทางฟิสิกส์: ขีดจำกัด Memory Bandwidth, การแย่งแคช L1/L2 และสถาปัตยกรรมเธรด 4 โหมด',
2846
+ sec31Title: '3.1 Memory Bandwidth Bottleneck & Compute Bounds',
2847
+ sec31P: 'ในการอนุมานผลลัพธ์ของโมเดลภาษา (Autoregressive Token Generation) ทุกๆ 1 โทเค็นที่สร้างขึ้น ซีพียูต้องโหลดน้ำหนักโมเดลทั้งหมด (Weights) ผ่านบัสหน่วยความจำอย่างน้อย 1 รอบเต็มเสมอ:',
2848
+ sec31MathMain: 'Maximum Tokens/sec &le; Memory Bandwidth (GB/s) &divide; Model Weight Size (GB)',
2849
+ sec31MathSub: 'สมการขีดจำกัดความเร็วสูงสุดทางทฤษฎีของการสร้างโทเค็นบนระบบ Memory-Bound',
2850
+ sec31P2: 'เปรียบเทียบแบนด์วิดท์จริงระหว่างหน่วยความจำหลัก (RAM) และหน่วยความจำการ์ดจอ (VRAM):',
2851
+ sec31L1: '<strong>Dual-Channel DDR4-3200:</strong> แบนด์วิดท์สูงสุด ~45–50 GB/s &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วสูงสุดไม่เกิน <strong>10–11 tokens/s</strong>',
2852
+ sec31L2: '<strong>Dual-Channel DDR5-6000:</strong> แบนด์วิดท์สูงสุด ~85–96 GB/s &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วสูงสุดไม่เกิน <strong>18–21 tokens/s</strong>',
2853
+ sec31L3: '<strong>RTX 3060 GDDR6 (192-bit):</strong> แบนด์วิดท์ <strong>360 GB/s</strong> &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็ว <strong>70–80 tokens/s</strong>',
2854
+ sec31L4: '<strong>RTX 4090 GDDR6X (384-bit):</strong> แบนด์วิดท์ <strong>1,008 GB/s</strong> &rarr; รันโมเดลขนาด 4.5 GB จะได้ความเร็วทะลุ <strong>150+ tokens/s</strong>',
2855
+ sec32Title: '3.2 SMT / Hyper-Threading Cache Eviction & Pipeline Thrashing',
2856
+ sec32P: 'เทคโนโลยี Simultaneous Multi-Threading (SMT ใน AMD หรือ Hyper-Threading ใน Intel) สร้าง Logical Threads เสมือนขึ้นมา 2 ตัวบนคอร์จริงอันเดียว แต่ทั้งสองเธรดต้องใช้ทรัพยากรฮาร์ดแวร์ภายในร่วมกัน:',
2857
+ sec32Warn: '<strong>ทำไม SMT ทำให้ LLM ช้าลง:</strong> การคูณเมทริกซ์ของ LLM รันบนหน่วยคำนวณทศนิยม (Floating Point Units / AVX2 / AVX-512) อย่างเข้มข้น 100% ต่อเนื่อง หากส่งเธรดคำนวณเข้าไป 2 เธรดพร้อมกัน เธรดทั้งสองจะเกิดการชนกันที่ Execution Ports และที่สำคัญที่สุดคือจะ <strong>ขับไล่ข้อมูลในแคช L1 และ L2 ทิ้ง (Cache Eviction)</strong> ส่งผลให้เกิด Cache Misses มหาศาล อัตราความเร็วในการสร้างโทเค็นจะ <strong>ร่วงลง 10% ถึง 25%!</strong>',
2858
+ sec33Title: '3.3 The 4 Thread Allocation Modes ใน <code>cpuMetrics.js</code>',
2859
+ sec33Th1: 'โหมด (htMode)',
2860
+ sec33Th2: 'สูตรคำนวณจำนวนเธรด',
2861
+ sec33Th3: 'พฤติกรรมและการจัดสรรทรัพยากร',
2862
+ sec33ChipRec: 'โหมดแนะนำสูงสุด',
2863
+ sec33R1C3: 'ล็อคจำนวนเธรดเท่ากับคอร์แท้เท่านั้น ขจัดปัญหาการแย่งแคช L1/L2 ให้ Single-stream latency ต่ำที่สุดและความเร็วสูงสุดสำหรับการแชท 1 ต่อ 1',
2864
+ sec33R2C3: 'เปิดใช้ทุกเธรดเสมือน เหมาะสำหรับสถานการณ์ที่ต้องการประมวลผลคำขอ Prompt Prefill พร้อมกันหลายผู้ใช้ (Throughput-oriented)',
2865
+ sec33R3C2: 'Heuristic จากสถาปัตยกรรม CPU',
2866
+ sec33R3C3: 'ตรวจจับโครงสร้างคอร์อัตโนมัติ หากตรวจพบว่าเป็นระบบที่มี SMT จะสงวนคอร์ไว้ 1-2 คอร์สำหรับงาน OS และ I/O',
2867
+ sec33R4C2: 'ผู้ใช้ระบุค่าอิสระ (1–256)',
2868
+ sec33R4C3: 'ยืดหยุ่นตามความต้องการของผู้ดูแลระบบ เหมาะสำหรับเซิร์ฟเวอร์แบบ NUMA Multi-Socket',
2869
+
2870
+ sec4Title: '4. การคำนวณ VRAM Footprint & Multi-GPU Math',
2871
+ sec4Sub: 'สูตรคำนวณทางคณิตศาสตร์ที่แม่นยำของ Model Weights, Hybrid SWA Attention และการจัดสรร Multi-GPU',
2872
+ sec4MathMain: 'Total VRAM Footprint = Weight Memory + KV Cache Memory + Activation & CUDA Overhead',
2873
+ sec4MathSub: 'งบประมาณหน่วยความจำวิดีโอทั้งหมดที่ต้องจัดสรรล่วงหน้าก่อนรันโมเดล',
2874
+ sec41Title: '4.1 Weight Memory Equation & BPW Math',
2875
+ sec41P: 'หน่วยความจำสำหรับบรรจุน้ำหนักโมเดลคำนวณจากจำนวนพารามิเตอร์คูณด้วย Bits Per Weight (BPW) หารด้วย 8:',
2876
+ sec41MathSub: 'ตัวอย่าง: โมเดล Gemma 4 E4B (8.0B parameters) ที่ Q4_K_M (BPW = 4.50) = (8.0 &times; 10&sup9; &times; 4.50) &divide; (8 &times; 1024&sup3;) &asymp; 4.19 GiB (4.50 GB)',
2877
+ sec41P2: 'กรณีที่มีการกระจายชั้นเลเยอร์บางส่วน (Fractional Offload):<br><code>Offloaded Weights (GB) = Total Weight Memory &times; (GPU Layers &divide; Total Layers)</code>',
2878
+ sec42Title: '4.2 Hybrid KV Attention Math & Sliding Window (SWA)',
2879
+ sec42P: 'สถาปัตยกรรม <strong>Gemma 4</strong> ไม่ได้ใช้ Attention แบบเต็มความยาวในทุกเลเยอร์ แต่ใช้ระบบลูกผสม <strong>Sliding Window Attention (SWA Profile) อัตราส่วน 5:1</strong>:',
2880
+ sec42L1: '<strong>Local Sliding Layers (5 ใน 6 เลเยอร์):</strong> บันทึก KV Cache เฉพาะหน้าต่าง 1,024 โทเค็นล่าสุดเท่านั้น (ความจำจะถูก Clamp ไว้ที่ 1,024 ไม่ว่า Context จะยาว 32K หรือ 64K ก็ตาม)',
2881
+ sec42L2: '<strong>Global Layers (1 ใน 6 เลเยอร์):</strong> บันทึกประวัติศาสตร์บริบทแบบเต็มความยาว Context Length ($L_{ctx}$)',
2882
+ sec42MathSub: 'H = Attention Heads, D = Head Dimension, B_val = Bytes Per Value ตามระดับการควอนต์',
2883
+ sec42P2: 'การลดขนาด KV Cache ตามชนิดข้อมูล (<code>KV_CACHE_DTYPE_BYTES</code>):<br>&bull; <code>fp16</code>: 2.00 Bytes/Value &bull; <code>q8_0</code>: 1.0625 Bytes/Value (ลดลง ~47%) &bull; <code>q4_0</code>: 0.5625 Bytes/Value (ลดลง ~72%)',
2884
+ sec43Title: '4.3 Activation Buffers & CUDA Runtime Overhead',
2885
+ sec43P: 'พื้นที่กันชนส่วนเกินคำนวณตามสูตรใน <code>src/lib/vram/estimator.js</code>:',
2886
+ sec43L1: '<strong>CUDA Context:</strong> พื้นที่สำหรับ CUDA Driver, Unified Virtual Addressing และโครงสร้าง Kernel ระหว่าง 0.35 GB ถึง 0.55 GB',
2887
+ sec43L2: '<strong>Intermediate Activations:</strong> อยู่ในช่วง 0.15 GB ถึง 0.35 GB (ค่าเริ่มต้น 0.25 GB) สำหรับจัดเก็บผลลัพธ์ระหว่างชั้นเลเยอร์',
2888
+ sec43L3: '<strong>LM Studio Engine Overhead:</strong> พื้นที่กันชน $0.60 \\text{ GB} + 0.10 \\text{ GB} \\times N_{GPUs}$ เพื่อป้องกันไดรเวอร์ NVIDIA แคชล้นจนเกิด Display Driver Crash (TDR)',
2889
+ sec44Title: '4.4 Multi-GPU Tensor Split & Balancing Heuristics',
2890
+ sec44P: 'เมื่อใช้งานเครื่องที่มีการ์ดจอมากกว่า 1 ใบ ระบบรองรับกลยุทธ์การกระจายโมเดล 2 รูปแบบ:',
2891
+ sec44Th1: 'กลยุทธ์',
2892
+ sec44Th2: 'พารามิเตอร์',
2893
+ sec44Th3: 'การเชื่อมต่อที่เหมาะสม',
2894
+ sec44Th4: 'ข้อดีและข้อจำกัด',
2895
+ sec44R1C3: 'PCIe Gen3 / Gen4 ธรรมดา (ไม่จำเป็นต้องมีบริดจ์)',
2896
+ sec44R1C4: 'แบ่งเลเยอร์ตามชั้น เหมาะสำหรับการ์ดจอที่มีขนาด VRAM ต่างกัน เช่น RTX 4080 (16GB) คู่กับ RTX 3060 (12GB) โดยกำหนดสัดส่วน <code>--tensor-split 16,12</code>',
2897
+ sec44R2C3: 'NVLink บริดจ์ความเร็วสูง หรือ PCIe 4.0 x16',
2898
+ sec44R2C4: 'ตัดแบ่งเมทริกซ์ภายในเลเยอร์ด้วย Tensor Parallelism ได้ Throughput สูงสุด แต่ต้องการการ์ดจอที่มีสเปกเหมือนกัน',
2899
+
2900
+ sec5Title: '5. ระบบค้นหาเครือข่ายภายใน (Zero-Key LAN Discovery)',
2901
+ sec5Sub: 'เทคโนโลยีสแกนค้นหาเครื่องแม่ข่าย AI ในวงแลนอัตโนมัติ การแยกแยะพอร์ต และกำแพงป้องกัน SSRF',
2902
+ sec51Title: '5.1 Network Interface Inspection & Concurrency Sweeper',
2903
+ sec51P: 'ระบบ <code>scanLan()</code> ใน <code>server/agent/lanDiscovery.js</code> ออกแบบมาเพื่อตรวจจับเครื่องแม่ข่าย AI ท้องถิ่นโดยที่ผู้ใช้ไม่ต้องเปิดเทอร์มินัลพิมพ์คำสั่ง <code>ipconfig</code> หรือป้อนที่อยู่ IP เอง:',
2904
+ sec51L1: '<strong>Cross-Platform Inspection:</strong> ตรวจจับการ์ดแลนและการ์ด Wi-Fi ผ่าน <code>os.networkInterfaces()</code> เสริมด้วย PowerShell Snapshot บน Windows (<code>Get-NetAdapter</code> + <code>Get-NetRoute</code>) หรือ <code>ip -j addr</code> บน Linux เพื่อนำ Netmask แท้จริงมาใช้คำนวณ Subnet',
2905
+ sec51L2: '<strong>Bounded Concurrency Pool:</strong> ใช้ระบบ TCP Connect Pre-filter แบบจำกัดปริมาณ Socket พร้อมกัน (~64 โฮสต์พร้อมกัน) เพื่อสแกนตรวจจับเป้าหมาย 2,500–3,000 จุด ให้เสร็จสิ้นภายในเวลาเพียง 15–20 วินาที โดยไม่ทำให้เราเตอร์ในบ้านค้าง',
2906
+ sec51L3: '<strong>Auto-Sweep Budget Packing:</strong> จัดเรียง Subnet จากขนาดเล็กไปใหญ่ และข้าม Subnet ที่มีขนาดเกินโควตาความปลอดภัย (<code>KIKU_LAN_SCAN_MAX_HOSTS = 4096</code>) เพื่อป้องกันการสแกนค้าง',
2907
+ sec52Title: '5.2 Probed Ports & Server Fingerprinting',
2908
+ sec52P: 'ทุกพอร์ตที่เปิดจะถูกตรวจสอบเชิงลึกเพื่อระบุชนิดของเครื่องยนต์และดึงรายชื่อโมเดลที่กำลังโหลดอยู่:',
2909
+ sec52Th1: 'พอร์ตเป้าหมาย',
2910
+ sec52Th2: 'เครื่องยนต์ที่คาดหวัง',
2911
+ sec52Th3: 'จุดตรวจสอบ Fingerprint',
2912
+ sec52Th4: 'ข้อมูลที่ส่งคืน',
2913
+ sec52R1C4: 'สถานะการโหลด, Quantization, Loaded Context Length',
2914
+ sec52R2C4: 'เวอร์ชัน vLLM, สถาปัตยกรรมโมเดล, Max Model Len',
2915
+ sec52R3C4: 'Tag โมเดลที่ดาวน์โหลดไว้ในระบบ',
2916
+ sec52R4C4: 'เวลาตอบสนอง (Round-Trip Latency) และรายชื่อโมเดล',
2917
+ sec53Title: '5.3 SSRF Defense, RFC1918 Pinning & Security Guard',
2918
+ sec53Warn: '<strong>การป้องกัน Server-Side Request Forgery (SSRF):</strong> โมดูล LAN Scanner มีระบบตรวจสอบที่อยู่เครือข่ายอย่างเข้มงวด โดยจำกัดขอบเขตการกวาดตรวจเฉพาะช่วง <strong>RFC1918 Private IPv4</strong> (<code>10.0.0.0/8</code>, <code>172.16.0.0/12</code>, <code>192.168.0.0/16</code>) และ Loopback (<code>127.0.0.1</code>) เท่านั้น หากมีการระบุ IP สาธารณะ หรือ Cloud Metadata Range (<code>169.254.169.254</code>) ระบบจะปฏิเสธคำขอทันที พร้อมทั้งจำกัดสิทธิ์การกด Apply ข้ามเครื่องให้เฉพาะ Local Loopback เท่านั้น',
2919
+
2920
+ sec6Title: '6. คู่มือคำสั่งและการปรับแต่งโมเดลเชิงลึก (Model Tuning & Commands)',
2921
+ sec6Sub: 'สารานุกรมคำสั่ง CLI แบบครบถ้วน, พารามิเตอร์การโหลดโมเดลเข้า VRAM และ Hyperparameters สำหรับ Sampling',
2922
+ sec6P: 'ส่วนนี้รวบรวมข้อมูลเชิงเทคนิคของการควบคุมโมเดล AI ในระบบ Kiku ทั้งหมด ตั้งแต่การใช้งานผ่าน Command Line Interface (CLI), การปรับแต่งพารามิเตอร์โหลดเข้าการ์ดจอ ไปจนถึงการจูนพารามิเตอร์สุ่มคำตอบ (Sampling Hyperparameters)',
2923
+ sec61Title: '6.1 สารานุกรมคำสั่ง CLI & Interactive Slash Commands',
2924
+ sec61P: 'ระบบรองรับคำสั่งทั้งในรูปแบบ One-Shot CLI สำหรับการสคริปต์อัตโนมัติ และ Interactive Slash Commands ภายในเทอร์มินัลหรือแชท:',
2925
+ cmd1Desc: 'รันคำสั่งถามตอบแบบครั้งเดียวจบ (Headless Execution) ทำงานผ่าน ReAct Agent เต็มรูปแบบ ค้นหาข้อมูลผลงาน ละคร เพลง และเว็บริเสิร์ชอัตโนมัติ เหมาะสำหรับตั้งเวลา Cron หรือไปป์คำสั่ง',
2926
+ cmd2Desc: 'กวาดสแกนหาเครื่องแม่ข่าย AI ภายในวงแลน (<code>/lan ifs</code> แสดงการ์ดเครือข่าย, <code>/lan scan --iface Wi-Fi</code> สแกนเฉพาะการ์ดนั้น, <code>/lan use 1</code> สลับไปเชื่อมต่อกับโฮสต์และพอร์ตของเครื่องที่ 1 พร้อมบันทึก Base URL อัตโนมัติ)',
2927
+ cmd3Desc: 'จัดการโมเดลและเครื่องยนต์ที่กำลังรันอยู่ ปรับแต่งอุณหภูมิ Sampling (<code>/model temp 0.2</code>), ปรับ Context Limit (<code>/model ctx 32768</code>), สั่งคืน VRAM (<code>/model unload</code>) หรือตรวจสอบสถานะการโหลด',
2928
+ cmd4Desc: 'สลับผู้ให้บริการ AI แบบทันที รองรับ <code>lmstudio</code>, <code>vllm</code>, <code>ollama</code>, <code>openai</code>, <code>gemini</code>, <code>groq</code>, <code>deepseek</code>, <code>anthropic</code>, และ <code>openrouter</code> พร้อมระบบตรวจสอบ Endpoint Latency',
2929
+ cmd5Desc: 'ตรวจสอบการใช้ VRAM แบบเรียลไทม์, อุณหภูมิ GPU, Bus Width, อัตราการรับส่ง PCIe และโครงสร้างคอร์ซีพียู SMT / Hyper-Threading',
2930
+ cmd6Desc: 'เปิดระบบทดสอบประสิทธิภาพโมเดล 500 ข้อ (Frozen Benchmark), สั่งเปิด Eval Studio Web Dashboard (Port 3001), รันชุดทดสอบ Enterprise 7-Point Model Compatibility (<code>npm run eval:compat</code>) หรือรันประเมินความถูกต้องด้านความปลอดภัย',
2931
+ cmd7Desc: 'คำนวณงบประมาณ VRAM ล่วงหน้าก่อนโหลดโมเดล แสดงตารางเปรียบเทียบขนาด KV Cache ตามความยาว Context และตรวจสอบว่าโมเดลจะฟิตลงในการ์ดจอหรือไม่',
2932
+ cmd8Desc: 'เชื่อมต่อไปยังเซิร์ฟเวอร์ Model Context Protocol (MCP) ภายนอก และควบคุม MCP Server ภายในระบบ (Streamable HTTP <code>POST /mcp</code>, Protocol 2025-11-25) รองรับการเชื่อมต่อจาก 10 ค่าย AI & IDEs (Claude Desktop, Cursor, Windsurf, VS Code, AGY, Cline, Claude Code, Gemini CLI, LibreChat, OpenCode)',
2933
+ cmd9Desc: 'แสดงความเร็วการสร้างโทเค็น (Prompt Tokens/s vs Eval Tokens/s) และสลับการแสดงผลกล่องความคิดภายใน (&lt;think&gt; / Thoughts) ของโมเดล Reasoning',
2934
+ sec62Title: '6.2 ตารางการปรับแต่งการโหลดโมเดลเข้า VRAM (Model Load Parameters)',
2935
+ sec62P: 'พารามิเตอร์ทั้งหมดในส่วนนี้ใช้ส่งผ่านคำสั่ง <code>lms load</code> หรือผ่าน REST API <code>POST /api/engine/load</code> เพื่อควบคุมพฤติกรรมในระดับไดรเวอร์และเคอร์เนล CUDA:',
2936
+ paramCtxDesc: 'กำหนดขนาดความยาวหน้าต่างบริบท (Context Window) มีผลต่อขนาดหน่วยความจำ KV Cache โดยตรง ยิ่งกำหนดสูง ยิ่งต้องใช้ VRAM มากขึ้น',
2937
+ paramGpuDesc: 'สัดส่วนการส่งชั้นเลเยอร์ของโมเดลเข้าการ์ดจอ <code>max</code> คือนำเข้า VRAM ทั้งหมด, <code>off</code> คือรันบน CPU ทั้งหมด หรือระบุเป็นทศนิยม <code>0.0 &ndash; 1.0</code>',
2938
+ paramHtDesc: 'ควบคุมการจัดสรรเธรดซีพียูตามโครงสร้าง Hyper-Threading/SMT โหมด <code>physical</code> ช่วยปิดการแย่งแคช L1/L2 ให้ความเร็วสร้างโทเค็นสูงสุด',
2939
+ paramFlashDesc: 'เปิดใช้เคอร์เนล FlashAttention-2 คำนวณ Attention Matrix แบบ Tiled บน SRAM ความเร็วสูง ลดความซับซ้อนหน่วยความจำจาก O(N&sup2;) เหลือ O(N)',
2940
+ paramBatchDesc: '<code>batchSize</code> ควบคุมการหั่นชิ้นประโยค Prompt ในระดับตรรกะ ส่วน <code>ubatchSize</code> ควบคุมขนาดสไลซ์ที่ส่งเข้าคำนวณใน CUDA Kernel ป้องกันอาการ VRAM พุ่งกระฉูดขณะอ่านคำถามยาว',
2941
+ paramSplitDesc: 'วิธีกระจายน้ำหนักโมเดลข้ามการ์ดจอหลายใบ <code>layer</code> สำหรับการ์ดจอขนาด VRAM ต่างกัน, <code>row</code> สำหรับการ์ดรุ่นเดียวกันที่มีบริดจ์ความเร็วสูง',
2942
+ paramKvDesc: 'บีบอัด Key และ Value ในหน่วยความจำบันทึกบทสนทนา โหมด <code>q8_0</code> ช่วยประหยัด VRAM ได้ 50% โดยสูญเสียความแม่นยำเพียง 0.2%',
2943
+ sec63Title: '6.3 การปรับแต่งการสุ่มคำตอบ (Inference Sampling Hyperparameters)',
2944
+ sec63P: 'พารามิเตอร์การประมวลผลคำตอบ (Logit Post-Processing &amp; Sampling) ซึ่งส่งผลต่อความแม่นยำ ความสร้างสรรค์ และการป้องกันคำตอบวนลูป:',
2945
+ paramTempDesc: 'ตัวปรับสเกลความน่าจะเป็นก่อนเข้า Softmax: สำหรับ ReAct Agent และงานเรียกใช้ Tools แนะนำ <strong>0.2 &ndash; 0.3</strong> เพื่อความแม่นยำสูงสุด, ค่า <strong>0.0</strong> สำหรับการทดสอบ Deterministic Benchmarking',
2946
+ paramMinpDesc: 'ตัดโทเค็นที่มีความน่าจะเป็นต่ำกว่าเกณฑ์สัมพัทธ์ ทำงานได้ดีกว่า <code>top_p</code> แบบเดิมสำหรับโมเดลตระกูล Gemma 4 อย่างเห็นได้ชัด เพราะปรับตัวตามความมั่นใจของโมเดลได้แบบไดนามิก',
2947
+ paramToppDesc: 'คัดเฉพาะกลุ่มโทเค็นที่มีผลรวมความน่าจะเป็นสะสมไม่เกินค่าที่กำหนด ในระบบ Kiku หากเปิดใช้งาน <code>min_p</code> ระบบจะปลดล็อค <code>top_p = 1.0</code> โดยอัตโนมัติเพื่อไม่ให้ขัดขวางการทำงานของ Min-P',
2948
+ paramRepeatDesc: 'ลดทอนค่า Logit ของโทเค็นที่เคยปรากฏในข้อความที่สร้างไปแล้ว ช่วยขจัดปัญหาโมเดลตอบวนซ้ำประโยคเดิม แต่ไม่ควรตั้งเกิน 1.25 เพราะจะทำให้โมเดลปฏิเสธการใช้คำศัพท์ไวยากรณ์ที่จำเป็น',
2949
+ paramTokensDesc: 'จำนวนโทเค็นสูงสุดที่โมเดลสามารถสร้างได้ในคำตอบเดียว ระบบได้สำรองพื้นที่บริบทสำหรับการตอบข้อยาว (Generation Reserve Buffer) ไว้ 8,192 โทเค็นเสมอ',
2950
+ sec64Title: '6.4 REST API Reference &amp; Code Playbook',
2951
+ sec64P: 'ตัวอย่างคำสั่ง cURL และโค้ด Node.js สำหรับนำไปเชื่อมต่อควบคุมการทำงานของ Inference Control Center แบบโปรแกรม:',
2952
+ sec64Api1Title: '1. ตรวจสอบ Telemetry ฮาร์ดแวร์ (GPU, VRAM และ CPU SMT)',
2953
+ sec64Api2Title: '2. สั่งโหลดโมเดลเข้า VRAM พร้อมกำหนด Hyper-Threading และ FlashAttention',
2954
+ sec64Api3Title: '3. ตัวอย่างการเขียนสคริปต์ Node.js สำหรับสั่งโหลดโมเดลอัตโนมัติ',
2955
+ sec64Api4Title: '4. สั่งปล่อยคืน VRAM ทั้งหมด (Unload Model)',
2956
+
2957
+ sec7Title: '7. คู่มือการปรับจูนและแก้ปัญหา (Tuning Playbook & OOM)',
2958
+ sec7Sub: 'ตารางการปรับแต่งตามสเปก VRAM, ขั้นตอนกู้วิกฤต VRAM Overflow และข้อควรระวัง PCIe Bus',
2959
+ sec71Title: '7.1 Hardware VRAM Tiers Matrix',
2960
+ sec71P: 'การปรับแต่งที่เหมาะสมที่สุดตามความจุการ์ดจอ เพื่อให้ได้ความเร็วในการสร้างโทเค็นสูงสุดและไม่เกิดอาการหน่วยความจำล้น:',
2961
+ sec71Th1: 'VRAM Capacity',
2962
+ sec71Th2: 'โมเดลและ Quantization แนะนำ',
2963
+ sec71Th3: 'Context &amp; KV Settings',
2964
+ sec71Th4: 'CPU SMT Mode',
2965
+ sec71R1C3: 'Context <strong>16,384</strong> (16K), KV Cache: <code>q4_0</code>, FlashAttn: เปิด',
2966
+ sec71R2C3: 'Context <strong>32,768</strong> (32K), KV Cache: <code>q8_0</code>, FlashAttn: เปิด',
2967
+ sec71R3C3: 'Context <strong>32,768 &ndash; 65,536</strong>, KV Cache: <code>q8_0</code> หรือ <code>fp16</code>',
2968
+ sec71R4C3: 'Context <strong>65,536+</strong>, Multi-GPU Split: <code>layer</code> หรือ <code>row</code>',
2969
+ sec72Title: '7.2 4-Step Deterministic Out-Of-Memory (OOM) Recovery',
2970
+ sec72P: 'หากแถบวัด VRAM ในหน้า Settings แสดงสถานะสีแดงเกิน 90% หรือไดรเวอร์เกิดข้อผิดพลาด <code>CUDA Out of Memory (exit code 1)</code> ให้ปฏิบัติตามลำดับ 4 ขั้นตอนนี้เพื่อกู้คืนระบบโดยไม่ต้องรีบูตเครื่อง:',
2971
+ sec72Step1: '<strong>ขั้นตอนที่ 1: บีบอัด KV Cache เป็น <code>q8_0</code> หรือ <code>q4_0</code></strong><br>ส่งผลให้ขนาด KV Cache ลดลงทันที 47% ถึง 72% ช่วยคืนพื้นที่ VRAM กลับมาได้ทันที 1.2 ถึง 2.5 GB โดยไม่จำเป็นต้องลดความยาว Context',
2972
+ sec72Step2: '<strong>ขั้นตอนที่ 2: ปรับลดความยาว Context Length ลงหนึ่งสเต็ป</strong><br>หากเดิมตั้งไว้ 32,768 ให้ปรับลดลงมาที่ 16,384 (16K) หรือ 8,192 (8K) ซึ่งเพียงพอสำหรับงานสนทนาและค้นคว้าทั่วไปถึง 95%',
2973
+ sec72Step3: '<strong>ขั้นตอนที่ 3: ตรวจสอบและเปิดใช้งาน <code>flashAttn = true</code></strong><br>ยืนยันว่าการ์ดจอรองรับ FlashAttention-2 เพื่อหลีกเลี่ยงการจัดสรร Memory Matrix ขนาดใหญ่ขณะทำ Prompt Prefill',
2974
+ sec72Step4: '<strong>ขั้นตอนที่ 4: ปรับสัดส่วน <code>gpuOffload</code> เป็นทศนิยม (เช่น <code>0.85</code>)</strong><br>สั่งให้ระบบแบ่งชั้นเลเยอร์ 15% ท้ายสุดไปรันบน System RAM แทนการบังคับยัดลงการ์ดจอทั้งหมด',
2975
+ sec73Title: '7.3 PCIe Bandwidth &amp; Partial Offloading Warning',
2976
+ sec73P: 'ข้อควรระวังสำคัญที่สุดในการตั้งค่า Partial Offload: ช่องเสียบ PCIe Gen3 x16 มีแบนด์วิดท์สูงสุดเพียง <strong>~15.75 GB/s</strong> (และ PCIe Gen3 x8 เพียง <strong>~7.8 GB/s</strong>) ซึ่งต่ำกว่า VRAM บนการ์ดจอ (360–1,000 GB/s) ถึง 25–60 เท่า!',
2977
+ sec73Warn: '<strong>คำเตือนเรื่องความเร็วร่วง (PCIe Thrashing):</strong> หากท่านปล่อยให้โมเดลล้นไปรันบน System RAM เพียง 2–3 เลเยอร์ ทุกๆ โทเค็นที่สร้างขึ้น ข้อมูลผลลัพธ์ระหว่างเลเยอร์จะต้องถูกส่งข้ามบัส PCIe สลับไปมาระหว่างการ์ดจอกับเมนบอร์ด ความเร็วการสร้างโทเค็นจะร่วงลงจาก 70 tokens/s เหลือเพียง <strong>8–12 tokens/s ทันที</strong> ดังนั้น ควรเลือกโมเดล Quantization ขนาดที่ <em>บรรจุลงใน VRAM ได้ 100%</em> เสมอเพื่อรักษาประสิทธิภาพสูงสุด'
2978
+ },
2979
+
2980
+ zh: {
2981
+ navBackSettings: '推理控制台',
2982
+ navBackChat: '返回对话',
2983
+ tocHeading: '文档目录 (Contents)',
2984
+ tocArch: '1. 系统整体架构',
2985
+ tocArch1: '1.1 三层套件拓扑与进程隔离',
2986
+ tocArch2: '1.2 ReAct 认知循环与上下文压缩',
2987
+ tocArch3: '1.3 原子级持久化队列与存储保障',
2988
+ tocEngines: '2. LM Studio vs vLLM 对比',
2989
+ tocEngines1: '2.1 Unified Memory 与 PagedAttention',
2990
+ tocEngines2: '2.2 GGUF 量化标度与 BPW 算力比',
2991
+ tocEngines3: '2.3 CLI 参数映射矩阵 (lms vs vLLM)',
2992
+ tocCpuHt: '3. CPU 超线程 / SMT 调度',
2993
+ tocCpu1: '3.1 内存带宽瓶颈与计算边界',
2994
+ tocCpu2: '3.2 SMT 缓存挤占与流水线颠簸',
2995
+ tocCpu3: '3.3 四种线程分配模式 (htMode)',
2996
+ tocVram: '4. 显存开销与多卡切分',
2997
+ tocVram1: '4.1 模型权重显存方程',
2998
+ tocVram2: '4.2 混合滑动窗口 KV 缓存算法',
2999
+ tocVram3: '4.3 激活缓存与 CUDA 运行时开销',
3000
+ tocVram4: '4.4 多卡张量切分策略 (Layer vs Row)',
3001
+ tocLan: '5. 零配置局域网探测',
3002
+ tocLan1: '5.1 网卡检测与并发扫描预算',
3003
+ tocLan2: '5.2 探测端口与引擎指纹识别',
3004
+ tocLan3: '5.3 SSRF 防御与 RFC1918 私网防护',
3005
+ tocApi: '6. 模型调优与指令手册',
3006
+ tocApi1: '6.1 CLI 命令行与交互式斜杠指令',
3007
+ tocApi2: '6.2 模型加载参数矩阵 (VRAM/CUDA)',
3008
+ tocApi3: '6.3 推理采样超参数 (Logits)',
3009
+ tocApi4: '6.4 REST API 参考与代码实战',
3010
+ tocTuning: '7. 硬件调优与防爆显存',
3011
+ tocTuning1: '7.1 硬件显存分级矩阵 (6GB–24GB+)',
3012
+ tocTuning2: '7.2 四步确定性防爆显存排障',
3013
+ tocTuning3: '7.3 PCIe 带宽瓶颈与部分卸载警示',
3014
+ heroBadge: '架构与工程设计指南',
3015
+ heroTitle: 'Inference Control Center 系统手册',
3016
+ heroSubtitle: 'AI 本地推理引擎、显存精准预估、CPU 物理核心/超线程拓扑调度及局域网自动嗅探深度技术指南。',
3017
+ hwBannerTitle: '当前系统硬件遥测状态 (Live Telemetry)',
3018
+ hwBannerMeta: '正在从 /api/v1/system/hardware 抓取传感器数据...',
3019
+ sec1Title: '1. 系统架构与三层数据流 (System Architecture & 3-Tier Data Flow)',
3020
+ sec1Sub: '进程隔离通信架构、ReAct 自主决策闭环与原子级持久化存储引擎',
3021
+ sec1P: 'Kiku Agent 系统建立在 <strong>三层模块化套件架构 (3-Tier Modular Suite Architecture)</strong> 之上，将前端展示 (Presentation)、编排控制与 Web 服务 (Orchestration & Web Server) 以及神经网络计算引擎 (Neural Compute Engine) 进行严格的进程解耦，防止高负载的推理任务阻碍界面的流畅交互。',
3022
+ sec11Title: '1.1 三层套件拓扑与进程隔离 (3-Tier Suite Topology)',
3023
+ sec11P: '三层之间的协同工作通过标准解耦的 IPC 与 HTTP 传输协议进行：',
3024
+ tier1Desc: 'Vite + React 19 + Tailwind CSS 4 单页应用 (SPA)，提供全量作品、历史生平及多媒体资源，采用 Liquid Glass 液态玻璃设计系统',
3025
+ tier2Desc: 'Node.js HTTP 服务器，充当 API 网关，托管主聊天界面、推理控制台 (/settings)、系统手册 (/docs)、REST API 路由及 Streamable HTTP Model Context Protocol (MCP) 服务端 (/mcp)',
3026
+ archArrow: '&#11015; OpenAI 兼容 REST、Server-Sent Events (SSE) 与子进程 IPC &#11015;',
3027
+ tier3aDesc: 'llama.cpp 引擎，支持 Windows、macOS (Metal) 与 Linux 跨平台运行，通过 lms CLI 管理 GGUF 量化模型',
3028
+ tier3bDesc: '企业级高吞吐引擎，运行于 WSL2 / Linux 环境，配备 PagedAttention 虚拟显存分页与持续批处理调度',
3029
+ tier3cDesc: '直连第三方云端服务，包括 Google Gemini、OpenAI、Groq、DeepSeek 及 OpenRouter，统一由 LLMClient 桥接',
3030
+ sec12Title: '1.2 ReAct 认知循环与上下文压缩 (ReAct Loop & Compaction)',
3031
+ sec12P: 'AI 代理核心采用 <strong>ReAct (Reasoning + Acting)</strong> 认知闭环，严格遵循<em>多因子动态评分排序 (Dynamic Score Ranking)</em> 机制调度工具，避免僵硬的 <code>if/else</code> 或单一硬编码正则分支：',
3032
+ sec12L1: '<strong>工具优先级加权评分 (Tool Priority Scoring)：</strong>候选工具通过定量公式评估：显式固定 (+100)、高优覆盖 (+20)、直接命中 (+10) 与衰减排名分，并设置集群配额上限，防止单一类型工具垄断上下文。',
3033
+ sec12L2: '<strong>上下文精简投影 (<code>compactToolResultForContext</code>)：</strong>工具返回的原始数据将过滤掉装饰性 URL 及冗余字段，仅保留核心字段注入提示词历史，大幅缩减上下文 Token 开销并降低大模型预填充延迟。',
3034
+ sec12L3: '<strong>四级上下文配额调度 (4-Tier Context Allocation)：</strong>20% 用户上下文、40% 当前活跃运行内存 (计划与检查点)、20% 长期知识与自省记录 (Reflections)、20% 通用对话与工具输出。',
3035
+ sec13Title: '1.3 原子级持久化队列与存储保障 (Atomic Persistence Queue)',
3036
+ sec13P: '推理引擎调优参数与运行时配置具备完整的双层持久化机制：',
3037
+ sec13Callout: '<strong>原子写入管道 (Atomic Write Pipeline)：</strong>当在页面中修改配置时，数据首先即时同步至浏览器的 <code>localStorage</code> 确保 0ms 的 UI 反馈；随后异步向服务器发起更新请求，由 <code>withSettingsWriteQueue()</code> 队列串行化处理，写入临时文件 <code>kiku_config.json.tmp</code> 后通过原子重命名完成替换，100% 杜绝意外宕机导致的配置文件损毁。',
3038
+
3039
+ sec2Title: '2. 推理引擎深度对比 (LM Studio vs vLLM)',
3040
+ sec2Sub: '底层架构差异、GGUF 量化标度解析与 CLI 参数 1:1 映射矩阵',
3041
+ sec21Title: '2.1 llama.cpp 统一内存 vs vLLM PagedAttention 显存分页',
3042
+ sec21P: '系统全面支持桌面级轻量引擎 (Consumer Desktop) 与数据中心级服务引擎 (Enterprise Serving)，两者在显存分配哲学上存在本质区别：',
3043
+ sec21Th1: '工程技术特性',
3044
+ sec21Th2: 'LM Studio (llama.cpp)',
3045
+ sec21Th3: 'vLLM (PagedAttention)',
3046
+ sec21R1C1: 'Core Architecture',
3047
+ sec21R1C2: 'C/C++ CUDA、Metal、ROCm 原生算子，融合 SIMD 向量化计算 (AVX2/AVX-512)',
3048
+ sec21R1C3: 'Python/C++ 定制 CUDA 算子，借鉴操作系统虚拟内存分页机制',
3049
+ sec21R2C1: '操作系统支持',
3050
+ sec21R2C2: 'Windows 10/11、macOS (Metal)、Linux 全平台原生支持',
3051
+ sec21R2C3: '仅限 Linux 原生环境或 Windows 11 WSL2 子系统 (不支持原生 Windows)',
3052
+ sec21R3C1: '模型权重格式',
3053
+ sec21R3C2: 'GGUF 单文件量化格式 (Q4_K_M, Q6_K, Q8_0)',
3054
+ sec21R3C3: 'HuggingFace SafeTensors、AWQ、GPTQ、FP8 Checkpoints',
3055
+ sec21R4C1: 'KV 缓存内存分配',
3056
+ sec21R4C2: '预先分配连续大块显存缓冲 (Contiguous VRAM Buffer)',
3057
+ sec21R4C3: '将 KV 缓存划分为离散物理页 (Paged Blocks)，显存碎片率降低至 &lt; 4%',
3058
+ sec21R5C1: '批处理调度策略',
3059
+ sec21R5C2: '静态 / 动态微批处理 (优先保障单流低延迟 Single-stream Latency)',
3060
+ sec21R5C3: '持续批处理 (Continuous Batching，迭代级动态调度)，支撑超高并发吞吐',
3061
+ sec21R6C1: '目标部署硬件',
3062
+ sec21R6C2: '消费级单显卡 (6GB、8GB、12GB) 或纯 CPU 混合卸载机器',
3063
+ sec21R6C3: '多卡工作站或企业级数据中心计算卡 (RTX 4090, A100, H100)',
3064
+ sec22Title: '2.2 GGUF 量化标度与 BPW 算力比 (GGUF Quantization)',
3065
+ sec22P: 'GGUF 采用 K-Quants 混合精度量化体系，根据网络各层对精度的敏感程度动态分配每参数比特数 (Bits Per Weight - BPW)：',
3066
+ sec22Th1: '量化档位',
3067
+ sec22Th2: '实际 BPW',
3068
+ sec22Th3: '8B 显存占用',
3069
+ sec22Th4: '困惑度增量 (&Delta;PPL)',
3070
+ sec22Th5: '工程推荐场景',
3071
+ sec22ChipRec: '推荐',
3072
+ sec22R1C5: '6GB 与 8GB 显卡最优解，兼顾推理速度与回答准确度的黄金平衡档',
3073
+ sec22R2C5: '适合在 8GB–12GB 显卡上追求更高中文与泰语语义表现的用户',
3074
+ sec22R3C5: '品质接近 FP16 无损水准，适配 12GB 及以上显卡 (如 RTX 4070)',
3075
+ sec22R4C5: '基准测试 (Benchmarking) 与科研评测基准，推荐 16GB+ 显存部署',
3076
+ sec22R5C5: '量化前原始半精度权重，仅用于学术研究与模型微调',
3077
+ sec23Title: '2.3 CLI 参数映射矩阵: LM Studio (lms) vs vLLM CLI',
3078
+ sec23P: 'LM Studio 与 vLLM CLI 核心控制参数 1:1 对齐映射表，便于开发者无缝切换引擎：',
3079
+ sec23Th1: '控制功能',
3080
+ sec23Th2: 'LM Studio (<code>lms load</code>)',
3081
+ sec23Th3: 'vLLM (<code>python -m vllm.entrypoints.openai.api_server</code>)',
3082
+ sec23R1C1: 'GPU 显存装载比例',
3083
+ sec23R2C1: '上下文窗口长度',
3084
+ sec23R3C1: '并发请求槽位数',
3085
+ sec23R4C1: '注意力加速算子',
3086
+ sec23R4C3: '默认自动启用 (使用 <code>--enforce-eager</code> 强制关闭)',
3087
+ sec23R5C1: '多 GPU 显存切分',
3088
+ sec23R6C1: 'KV 缓存量化格式',
3089
+
3090
+ sec3Title: '3. CPU 超线程与 SMT 拓扑调度 (CPU SMT Topology)',
3091
+ sec3Sub: '物理层瓶颈解析：内存总线带宽限制、L1/L2 缓存挤占与四种线程调度模式',
3092
+ sec31Title: '3.1 内存带宽瓶颈与计算边界 (Memory Bandwidth Bottleneck)',
3093
+ sec31P: '在大语言模型自回归生成 (Autoregressive Token Generation) 阶段，每产生 1 个新 Token，计算单元都必须完整读取一遍全部模型权重：',
3094
+ sec31MathMain: 'Maximum Tokens/sec &le; Memory Bandwidth (GB/s) &divide; Model Weight Size (GB)',
3095
+ sec31MathSub: '内存受限 (Memory-Bound) 系统下 Token 生成速度理论物理上限方程',
3096
+ sec31P2: '系统主内存 (RAM) 与显卡显存 (VRAM) 实际传输带宽对比：',
3097
+ sec31L1: '<strong>双通道 DDR4-3200：</strong>峰值带宽约 45–50 GB/s &rarr; 运行 4.5 GB 模型速度上限不超过 <strong>10–11 tokens/s</strong>',
3098
+ sec31L2: '<strong>双通道 DDR5-6000：</strong>峰值带宽约 85–96 GB/s &rarr; 运行 4.5 GB 模型速度上限不超过 <strong>18–21 tokens/s</strong>',
3099
+ sec31L3: '<strong>RTX 3060 GDDR6 (192-bit)：</strong>带宽高达 <strong>360 GB/s</strong> &rarr; 运行 4.5 GB 模型生成速度达 <strong>70–80 tokens/s</strong>',
3100
+ sec31L4: '<strong>RTX 4090 GDDR6X (384-bit)：</strong>带宽高达 <strong>1,008 GB/s</strong> &rarr; 运行 4.5 GB 模型生成速度轻松突破 <strong>150+ tokens/s</strong>',
3101
+ sec32Title: '3.2 SMT 缓存挤占与流水线颠簸 (SMT Cache Thrashing)',
3102
+ sec32P: '同步多线程技术 (AMD SMT 或 Intel Hyper-Threading) 在单个物理核心上派生两个逻辑线程，两者共享执行单元与高速缓存：',
3103
+ sec32Warn: '<strong>为什么开启 SMT 会导致 LLM 推理变慢：</strong>大模型矩阵乘法高度依赖浮点向量单元 (FPU / AVX2 / AVX-512) 的持续满负荷运转。当两个高负载线程并发注入同一物理核心时，会在执行端口产生严重争用，更致命的是会导致 <strong>L1/L2 缓存被反复置换冲刷 (Cache Eviction)</strong>，引发灾难级 Cache Misses，导致 Token 生成速度<strong>暴跌 10% 至 25%！</strong>',
3104
+ sec33Title: '3.3 四种线程分配模式 (The 4 Thread Allocation Modes)',
3105
+ sec33Th1: '模式 (htMode)',
3106
+ sec33Th2: '线程数计算公式',
3107
+ sec33Th3: '行为特征与调度机制',
3108
+ sec33ChipRec: '首选推荐模式',
3109
+ sec33R1C3: '仅绑定物理核心数量，杜绝 L1/L2 缓存争夺，为单流 1:1 对话提供最低延迟与极速生成体验。',
3110
+ sec33R2C3: '启用所有逻辑虚拟线程，适合需要并发处理多用户提示词预填充 (Prompt Prefill) 的高吞吐服务场景。',
3111
+ sec33R3C2: 'CPU 架构自适应启发式',
3112
+ sec33R3C3: '自动探查核心拓扑，若检测到多核 SMT 环境，自动预留 1–2 个物理核心供操作系统和 I/O 调度。',
3113
+ sec33R4C2: '操作员自定义数值 (1–256)',
3114
+ sec33R4C3: '供管理员按需精细调整，适用于 NUMA 多路多插槽服务器绑定特定 CPU 节点。',
3115
+
3116
+ sec4Title: '4. 显存开销精准测算与多卡并行算法 (VRAM Math & Multi-GPU)',
3117
+ sec4Sub: '模型权重、混合滑动窗口注意力机制 (SWA) 与多卡张量并行数学模型',
3118
+ sec4MathMain: 'Total VRAM Footprint = Weight Memory + KV Cache Memory + Activation & CUDA Overhead',
3119
+ sec4MathSub: '模型加载前必须精确预留的总显存预算公式',
3120
+ sec41Title: '4.1 模型权重显存方程与 BPW 算法 (Weight Memory Equation)',
3121
+ sec41P: '模型权重的显存开销由总参数量乘以每权重比特数 (BPW) 再除以 8 计算得出：',
3122
+ sec41MathSub: '计算范例：Gemma 4 E4B (80亿参数) 采用 Q4_K_M 量化 (BPW = 4.50) = (8.0 &times; 10&sup9; &times; 4.50) &divide; (8 &times; 1024&sup3;) &asymp; 4.19 GiB (4.50 GB)',
3123
+ sec41P2: '部分层卸载 (Fractional Offload) 显存计算公式：<br><code>Offloaded Weights (GB) = Total Weight Memory &times; (GPU Layers &divide; Total Layers)</code>',
3124
+ sec42Title: '4.2 混合滑动窗口 KV 缓存算法 (Hybrid SWA Math)',
3125
+ sec42P: '<strong>Gemma 4</strong> 架构并未在所有网络层使用全量注意力，而是采用了 <strong>5:1 混合滑动窗口注意力体系 (Sliding Window Attention, SWA)</strong>：',
3126
+ sec42L1: '<strong>局部滑动层 (Local Sliding Layers，每 6 层中占 5 层)：</strong>仅保留最近 1,024 个 Token 的 KV 缓存 (显存占用被永久锁定在 1,024，即便上下文设为 32K 或 64K 也不会增加)',
3127
+ sec42L2: '<strong>全局注意力层 (Global Layers，每 6 层中占 1 层)：</strong>维护覆盖全上下文长度 ($L_{ctx}$) 的全局历史记忆',
3128
+ sec42MathSub: 'H = 注意力头数，D = 头维度，B_val = 单精度/量化值字节数',
3129
+ sec42P2: 'KV 缓存按精度类型的压缩比 (<code>KV_CACHE_DTYPE_BYTES</code>)：<br>&bull; <code>fp16</code>：2.00 字节/值 &bull; <code>q8_0</code>：1.0625 字节/值 (节省 ~47%) &bull; <code>q4_0</code>：0.5625 字节/值 (节省 ~72%)',
3130
+ sec43Title: '4.3 激活缓存与 CUDA 运行时开销 (Activation & CUDA Overhead)',
3131
+ sec43P: '附加运行时显存开销基于 <code>src/lib/vram/estimator.js</code> 预估模型精确计算：',
3132
+ sec43L1: '<strong>CUDA Context 上下文：</strong>包含显卡驱动程序、统一虚拟地址寻址及核心算子开销，固定占用 0.35 GB 至 0.55 GB',
3133
+ sec43L2: '<strong>Intermediate Activations 激活缓冲：</strong>用于存储层间计算中间变量，介于 0.15 GB 至 0.35 GB (默认 0.25 GB)',
3134
+ sec43L3: '<strong>LM Studio 运行时裕量：</strong>预留 $0.60 \\text{ GB} + 0.10 \\text{ GB} \\times N_{GPUs}$ 缓冲带，防止显存瞬时溢出触发 NVIDIA 显示驱动重置 (TDR Crash)',
3135
+ sec44Title: '4.4 多卡张量切分策略 (Multi-GPU Tensor Split)',
3136
+ sec44P: '当在配备多张显卡的系统上部署时，系统支持两种模型分片调度模式：',
3137
+ sec44Th1: '切分策略',
3138
+ sec44Th2: '控制参数',
3139
+ sec44Th3: '适用互联通道',
3140
+ sec44Th4: '优势与约束',
3141
+ sec44R1C3: '普通 PCIe Gen3 / Gen4 插槽 (无需桥接器)',
3142
+ sec44R1C4: '按网络层垂直切分，完美支持异构显卡混插 (如 RTX 4080 16GB 搭配 RTX 3060 12GB)，显存分配比指定为 <code>--tensor-split 16,12</code>',
3143
+ sec44R2C3: '高速 NVLink 桥接或全速 PCIe 4.0 x16',
3144
+ sec44R2C4: '层内水平切分张量并行 (Tensor Parallelism)，计算吞吐性能最高，但必须配备同款型号与等额显存的显卡',
3145
+
3146
+ sec5Title: '5. 零配置局域网引擎嗅探 (Zero-Key LAN Discovery)',
3147
+ sec5Sub: '局域网自动嗅探 AI 服务节点、引擎端口指纹鉴别与 SSRF 安全防御边界',
3148
+ sec51Title: '5.1 网卡检测与并发扫描预算 (Network Interface Inspection)',
3149
+ sec51P: '<code>server/agent/lanDiscovery.js</code> 中的 <code>scanLan()</code> 引擎旨在实现零配置探测局域网内所有本地 AI 服务器，无需手动查询 <code>ipconfig</code> 或输入 IP：',
3150
+ sec51L1: '<strong>跨平台真实网卡探查：</strong>通过 <code>os.networkInterfaces()</code> 获取网卡基线，结合 Windows PowerShell (<code>Get-NetAdapter</code> + <code>Get-NetRoute</code>) 或 Linux <code>ip -j addr</code> 提取真实掩码计算精确子网',
3151
+ sec51L2: '<strong>受限高并发扫描池 (Bounded Concurrency Pool)：</strong>采用 TCP 连接预过滤技术，限制并发 Socket 数量 (~64 并发)，在 15–20 秒内完整扫描 2,500–3,000 个探测点，彻底避免家用路由器死机',
3152
+ sec51L3: '<strong>智能预算装箱 (Budget Packing)：</strong>按子网主机规模升序优先扫描小网段，主动跳过超额网段 (<code>KIKU_LAN_SCAN_MAX_HOSTS = 4096</code>)，防止任务超时',
3153
+ sec52Title: '5.2 探测端口与引擎指纹识别 (Probed Ports & Fingerprint)',
3154
+ sec52P: '每个开放端口均由专门协议探针进行指纹识别，获取正在载入的模型与运行时指标：',
3155
+ sec52Th1: '目标端口',
3156
+ sec52Th2: '预期推理引擎',
3157
+ sec52Th3: '指纹探针端点',
3158
+ sec52Th4: '回传信息',
3159
+ sec52R1C4: '模型装载状态、量化档位、已分配上下文长度',
3160
+ sec52R2C4: 'vLLM 版本号、模型架构标识、最大模型长度',
3161
+ sec52R3C4: '本地已拉取的模型标签列表',
3162
+ sec52R4C4: '往返延迟 (Latency) 及已装载模型清单',
3163
+ sec53Title: '5.3 SSRF 防御与 RFC1918 私网防护 (SSRF & Security Guard)',
3164
+ sec53Warn: '<strong>服务器端请求伪造 (SSRF) 防御：</strong>局域网扫描引擎配备严格的网络边界守卫，探测范围严格限制于 <strong>RFC1918 私有网段</strong> (<code>10.0.0.0/8</code>, <code>172.16.0.0/12</code>, <code>192.168.0.0/16</code>) 及本地回环 (<code>127.0.0.1</code>)。严禁扫描公网 IP 或云服务元数据地址 (<code>169.254.169.254</code>)，且跨主机应用配置 (Apply) 接口默认仅对回环客户端开放。',
3165
+
3166
+ sec6Title: '6. 模型调优与指令手册 (Model Tuning & Commands)',
3167
+ sec6Sub: '全量 CLI 与斜杠指令字典、VRAM 显存加载矩阵与推理采样超参数解析',
3168
+ sec6P: '本章节汇总了 Kiku AI 系统的所有高级控制方式，涵盖命令行接口 (CLI)、显存装载参数矩阵以及生成采样超参数 (Sampling Hyperparameters) 的深度调优技巧。',
3169
+ sec61Title: '6.1 CLI 命令行与交互式斜杠指令 (Commands Encyclopedia)',
3170
+ sec61P: '系统支持面向自动化脚本的单次 CLI 模式与面向终端/网页会话的交互式斜杠指令：',
3171
+ cmd1Desc: '无头单次执行指令，驱动完整 ReAct 代理闭环，自主执行多因子作品检索与网络研究，适合 Cron 定时任务与管道调用。',
3172
+ cmd2Desc: '局域网自动嗅探 (<code>/lan ifs</code> 查看物理网卡，<code>/lan scan --iface Wi-Fi</code> 指定网卡扫描，<code>/lan use 1</code> 自动连接第1台服务器并持久化 Base URL)。',
3173
+ cmd3Desc: '管理正在运行的模型与引擎状态，微调采样温度 (<code>/model temp 0.2</code>)、调整上下文长度 (<code>/model ctx 32768</code>) 或释放显存 (<code>/model unload</code>)。',
3174
+ cmd4Desc: '实时切换 AI 服务商，支持 <code>lmstudio</code>、<code>vllm</code>、<code>ollama</code>、<code>openai</code>、<code>gemini</code>、<code>groq</code>、<code>deepseek</code>、<code>anthropic</code> 及 <code>openrouter</code>，配备端点延迟测速',
3175
+ cmd5Desc: '硬件遥测：实时监测显存占用率、GPU 温度、显存位宽、PCIe 吞吐速率以及 CPU SMT 超线程拓扑状态。',
3176
+ cmd6Desc: '运行 500 道基准测试 (Frozen Benchmark)、启动 Eval Studio 网页工作台 (Port 3001)、执行企业级 7 维模型兼容性探针 (<code>npm run eval:compat</code>) 或运行安全审计',
3177
+ cmd7Desc: '显存预估器：在加载模型前精确预估显存开销，输出各上下文长度下的 KV 缓存比对表，检查模型是否能完全塞入显存。',
3178
+ cmd8Desc: 'MCP 协议桥接：挂载外部 MCP 服务端，并控制内置 Streamable HTTP <code>POST /mcp</code> (协议版本 2025-11-25)，全面兼容 10 款 AI 客户端与 IDE (Claude Desktop, Cursor, Windsurf, VS Code, AGY, Cline, Claude Code, Gemini CLI, LibreChat, OpenCode)',
3179
+ cmd9Desc: '性能指标与思维链切换：展示生成速率 (Prompt vs Eval tok/s) 并切换推理模型内置思考框 (&lt;think&gt; / Thoughts) 的展示。',
3180
+ sec62Title: '6.2 模型加载与显存配置矩阵 (Model Load Parameters)',
3181
+ sec62P: '本节参数通过 <code>lms load</code> 或 REST API <code>POST /api/engine/load</code> 注入，用于精确控制显卡驱动及底层 CUDA 算子行为：',
3182
+ paramCtxDesc: '设定上下文窗口长度 (Context Window)，直接决定 KV 缓存显存分配大小，数值越高显存占用越大。',
3183
+ paramGpuDesc: 'GPU 显存卸载比例。<code>max</code> 为全量载入显存，<code>off</code> 为纯 CPU 运算，亦可指定小数 <code>0.0 &ndash; 1.0</code>。',
3184
+ paramHtDesc: 'CPU 线程分配模式。<code>physical</code> 仅使用物理核心，消除 L1/L2 缓存竞争，生成速度最高提升 25%。',
3185
+ paramFlashDesc: '开启 FlashAttention-2 高速算子，在片上 SRAM 上分块计算注意力，将显存复杂度从 O(N&sup2;) 压缩至 O(N)。',
3186
+ paramBatchDesc: '<code>batchSize</code> 控制逻辑批处理块大小，<code>ubatchSize</code> 控制送入 CUDA 核心的物理切片，防止长提示词引发显存瞬时峰值溢出。',
3187
+ paramSplitDesc: '多 GPU 显存切分模式。<code>layer</code> 适配异构显卡混插，<code>row</code> 适配配备高速互联桥同型号显卡。',
3188
+ paramKvDesc: 'KV 缓存量化压缩。<code>q8_0</code> 可节省近 50% KV 显存占用，精度损耗仅 0.2%。',
3189
+ sec63Title: '6.3 推理采样超参数调优 (Sampling Hyperparameters)',
3190
+ sec63P: '用于控制大模型输出概率分布 (Logits) 的超参数，直接影响回答的准确度、创造力以及防车轱辘话循环机制：',
3191
+ paramTempDesc: 'Softmax 概率分布缩放因子。执行 ReAct 代理与工具调用时建议设为 <strong>0.2 &ndash; 0.3</strong> 以保障输出严谨度，<strong>0.0</strong> 用于确定性基准测试。',
3192
+ paramMinpDesc: '截断相对概率低于最高概率设定比例的候选词，在 Gemma 4 系列模型上的实际表现显著优于传统 <code>top_p</code>。',
3193
+ paramToppDesc: '累积概率核采样。在 Kiku 系统中，若启用了 <code>min_p</code>，系统会自动将 <code>top_p</code> 放宽至 1.0 以避免采样器相互冲突。',
3194
+ paramRepeatDesc: '惩罚已出现的重复 Token，杜绝车轱辘话循环。建议值 1.10，不应超过 1.25，否则会破坏正常语法连贯性。',
3195
+ paramTokensDesc: '单次回答最大生成 Token 数。系统预留了 8,192 Token 作为长文回答安全缓冲带。',
3196
+ sec64Title: '6.4 REST API 参考与代码实战 (REST API Playbook)',
3197
+ sec64P: '用于通过编程方式远程控制 Inference Control Center 的 cURL 范例与 Node.js 代码片段：',
3198
+ sec64Api1Title: '1. 硬件遥测监测 (GPU, VRAM 与 CPU SMT)',
3199
+ sec64Api2Title: '2. 加载模型至显存并配置超线程与 FlashAttention',
3200
+ sec64Api3Title: '3. Node.js 自动化模型加载实战脚本',
3201
+ sec64Api4Title: '4. 释放显存占用 (Unload Model)',
3202
+
3203
+ sec7Title: '7. 硬件调优与防爆显存指南 (Tuning Playbook & OOM)',
3204
+ sec7Sub: '显存分级配置矩阵、四步防爆显存救急方案与 PCIe 物理总线警示',
3205
+ sec71Title: '7.1 硬件显存分级矩阵 (Hardware VRAM Tiers)',
3206
+ sec71P: '按主流显存规格定制的最佳配置方案，实现极速生成且 100% 避免显存溢出：',
3207
+ sec71Th1: '显存容量',
3208
+ sec71Th2: '推荐模型与量化档位',
3209
+ sec71Th3: '上下文与 KV 缓存配置',
3210
+ sec71Th4: 'CPU SMT 线程模式',
3211
+ sec71R1C3: '上下文 <strong>16,384</strong> (16K), KV 缓存: <code>q4_0</code>, FlashAttn: 开启',
3212
+ sec71R2C3: '上下文 <strong>32,768</strong> (32K), KV 缓存: <code>q8_0</code>, FlashAttn: 开启',
3213
+ sec71R3C3: '上下文 <strong>32,768 &ndash; 65,536</strong>, KV 缓存: <code>q8_0</code> 或 <code>fp16</code>',
3214
+ sec71R4C3: '上下文 <strong>65,536+</strong>, 多卡切分: <code>layer</code> 或 <code>row</code>',
3215
+ sec72Title: '7.2 四步确定性防爆显存排障 (4-Step OOM Recovery)',
3216
+ sec72P: '当控制台显存状态条红警超过 90% 或驱动报错 <code>CUDA Out of Memory</code> 时，严格按以下 4 步梯次恢复系统，无需重启机器：',
3217
+ sec72Step1: '<strong>第 1 步：将 KV 缓存压缩为 <code>q8_0</code> 或 <code>q4_0</code></strong><br>KV 缓存体积立减 47% 至 72%，瞬间腾出 1.2 至 2.5 GB 宝贵显存，无需削减上下文长度。',
3218
+ sec72Step2: '<strong>第 2 步：将 Context Length 降档一阶</strong><br>原为 32,768 则降至 16,384 (16K) 或 8,192 (8K)，足以满足 95% 的日常对话与检索任务。',
3219
+ sec72Step3: '<strong>第 3 步：确认开启 <code>flashAttn = true</code></strong><br>确保启用 FlashAttention-2，避免提示词预填充时因二次方内存膨胀而爆显存。',
3220
+ sec72Step4: '<strong>第 4 步：将 <code>gpuOffload</code> 改设为浮点比例 (如 <code>0.85</code>)</strong><br>将最后 15% 的顶层网络卸载至系统内存运算，避免强制塞入显存导致崩溃。',
3221
+ sec73Title: '7.3 PCIe 带宽瓶颈与部分卸载警示 (PCIe Bandwidth Warning)',
3222
+ sec73P: '部分卸载极度重要警示：PCIe Gen3 x16 总线带宽仅 <strong>~15.75 GB/s</strong> (Gen3 x8 仅 <strong>~7.8 GB/s</strong>)，比显存带宽 (360–1,000 GB/s) 慢 25–60 倍！',
3223
+ sec73Warn: '<strong>总线颠簸性能暴跌警示 (PCIe Thrashing)：</strong>哪怕仅有 2–3 层网络溢出到系统内存，每生成一个 Token，层间张量都必须在 PCIe 总线上来回搬运，生成速度会从 70 tokens/s <strong>瞬间暴跌至 8–12 tokens/s！</strong>因此务必优先选用能够 <em>100% 完整容纳于显存中</em> 的模型量化版本！'
3224
+ },
3225
+
3226
+ en: {
3227
+ navBackSettings: 'Inference Controls',
3228
+ navBackChat: 'Chat',
3229
+ tocHeading: 'Table of Contents',
3230
+ tocArch: '1. System Architecture',
3231
+ tocArch1: '1.1 3-Tier Suite Topology',
3232
+ tocArch2: '1.2 ReAct Loop & Compaction',
3233
+ tocArch3: '1.3 Atomic Persistence Queue',
3234
+ tocEngines: '2. LM Studio vs vLLM',
3235
+ tocEngines1: '2.1 Unified Memory vs PagedAttention',
3236
+ tocEngines2: '2.2 GGUF Quantization Scales',
3237
+ tocEngines3: '2.3 CLI Flag Matrix',
3238
+ tocCpuHt: '3. CPU Hyper-Threading / SMT',
3239
+ tocCpu1: '3.1 Bandwidth Bottleneck & Compute',
3240
+ tocCpu2: '3.2 SMT Cache Thrashing',
3241
+ tocCpu3: '3.3 The 4 htMode Settings',
3242
+ tocVram: '4. VRAM Footprint & Multi-GPU',
3243
+ tocVram1: '4.1 Weight Memory Equation',
3244
+ tocVram2: '4.2 Hybrid KV Attention Math',
3245
+ tocVram3: '4.3 Activation & CUDA Overhead',
3246
+ tocVram4: '4.4 Tensor Split Heuristic',
3247
+ tocLan: '5. Zero-Key LAN Discovery',
3248
+ tocLan1: '5.1 Concurrency & Sweep Budget',
3249
+ tocLan2: '5.2 Probed Ports & Fingerprint',
3250
+ tocLan3: '5.3 SSRF & RFC1918 Guard',
3251
+ tocApi: '6. Model Tuning & Commands',
3252
+ tocApi1: '6.1 CLI & Slash Commands',
3253
+ tocApi2: '6.2 Load Parameter Matrix',
3254
+ tocApi3: '6.3 Sampling Hyperparameters',
3255
+ tocApi4: '6.4 REST API Code Playbook',
3256
+ tocTuning: '7. Tuning Playbook & OOM',
3257
+ tocTuning1: '7.1 Hardware VRAM Tiers',
3258
+ tocTuning2: '7.2 4-Step OOM Recovery',
3259
+ tocTuning3: '7.3 PCIe Bandwidth & Bus',
3260
+ heroBadge: 'Architecture & Engineering Manual',
3261
+ heroTitle: 'Inference Control Center Architecture',
3262
+ heroSubtitle: 'Comprehensive technical manual covering local inference engines, predictive VRAM math, CPU SMT allocation topology, and zero-config LAN discovery.',
3263
+ hwBannerTitle: 'Current System Hardware Telemetry (Live Telemetry)',
3264
+ hwBannerMeta: 'Fetching live sensor metrics from /api/v1/system/hardware...',
3265
+ sec1Title: '1. System Architecture & 3-Tier Data Flow',
3266
+ sec1Sub: 'Decoupled process isolation, ReAct cognitive decision loop, and atomic persistence storage',
3267
+ sec1P: 'The Kiku Agent system is engineered on a decoupled <strong>3-Tier Modular Suite Architecture</strong> to strictly isolate the Presentation tier, Orchestration/Web tier, and Neural Compute Engine, preventing resource-heavy inference tasks from blocking user interface responsiveness.',
3268
+ sec11Title: '1.1 3-Tier Suite Topology & Process Isolation',
3269
+ sec11P: 'The three layers communicate via standard decoupled IPC and HTTP transport protocols:',
3270
+ tier1Desc: 'Vite + React 19 + Tailwind CSS 4 Single Page Application (SPA) delivering biography, discography, and multimedia catalog via Liquid Glass design system.',
3271
+ tier2Desc: 'Node.js HTTP server acting as API Gateway, hosting Web Chat, Inference Control Center (/settings), Architecture Manual (/docs), REST API routes, and Streamable HTTP Model Context Protocol (MCP) Server (/mcp).',
3272
+ archArrow: '&#11015; OpenAI-Compatible REST, Server-Sent Events (SSE) & Child Process IPC &#11015;',
3273
+ tier3aDesc: 'llama.cpp engine supporting Windows, macOS (Metal), and Linux, serving GGUF quantized models via lms CLI.',
3274
+ tier3bDesc: 'Enterprise high-throughput engine running on WSL2 / Linux with PagedAttention virtual memory paging and continuous batching.',
3275
+ tier3cDesc: 'Direct connection to cloud APIs including Google Gemini, OpenAI, Groq, DeepSeek, and OpenRouter via unified LLMClient.',
3276
+ sec12Title: '1.2 ReAct Cognitive Loop & Context Compaction',
3277
+ sec12P: 'The agent cognitive engine operates on a <strong>ReAct (Reasoning + Acting)</strong> loop governed by <em>Dynamic Multi-Factor Score Ranking</em> for tool arbitration, strictly rejecting rigid <code>if/else</code> ladders or single-keyword traps:',
3278
+ sec12L1: '<strong>Tool Priority Scoring:</strong> Tools are evaluated by an additive scoring formula combining explicit pinning (+100), high-priority overrides (+20), direct selection (+10), and decaying intent rank scoring, constrained by cluster quota caps.',
3279
+ sec12L2: '<strong>Context Compactor (<code>compactToolResultForContext</code>):</strong> Raw tool returns project essential keys and strip decorative URLs from prompt history to minimize token consumption and slash LLM reasoning latency.',
3280
+ sec12L3: '<strong>4-Tier Context Allocation:</strong> 20% user context, 40% active run memory (plan & checkpoints), 20% long-term knowledge & reflections, 20% general dialogue and tool outputs.',
3281
+ sec13Title: '1.3 Atomic Persistence Queue & Storage Guarantees',
3282
+ sec13P: 'Engine parameters and inference configurations are backed by a complete two-tier persistence mechanism:',
3283
+ sec13Callout: '<strong>Atomic Write Pipeline:</strong> Configuration changes immediately persist to browser <code>localStorage</code> for 0ms UI responsiveness, while asynchronously sending updates to the Node server. Server writes are serialized via <code>withSettingsWriteQueue()</code> into a <code>kiku_config.json.tmp</code> file before atomic renaming, 100% preventing configuration corruption during power outages.',
3284
+
3285
+ sec2Title: '2. Inference Engine Comparison (LM Studio vs vLLM)',
3286
+ sec2Sub: 'Architectural divergences, GGUF quantization scales, and 1:1 CLI parameter mapping',
3287
+ sec21Title: '2.1 llama.cpp Unified Memory vs vLLM PagedAttention',
3288
+ sec21P: 'The system supports both desktop-grade engines (Consumer Desktop) and datacenter-grade engines (Enterprise Serving), built on distinct memory management architectures:',
3289
+ sec21Th1: 'Engineering Characteristics',
3290
+ sec21Th2: 'LM Studio (llama.cpp)',
3291
+ sec21Th3: 'vLLM (PagedAttention)',
3292
+ sec21R1C1: 'Core Architecture',
3293
+ sec21R1C2: 'C/C++ CUDA, Metal, ROCm kernels with SIMD vector extensions (AVX2/AVX-512)',
3294
+ sec21R1C3: 'Python/C++ custom CUDA kernels modeled on OS virtual memory paging',
3295
+ sec21R2C1: 'Supported Operating Systems',
3296
+ sec21R2C2: 'Windows 10/11, macOS (Apple Silicon Metal), Linux',
3297
+ sec21R2C3: 'Linux native or Windows 11 via WSL2 only (no native Windows support)',
3298
+ sec21R3C1: 'Model Weight Formats',
3299
+ sec21R3C2: 'GGUF single-file quantizations (Q4_K_M, Q6_K, Q8_0)',
3300
+ sec21R3C3: 'HuggingFace SafeTensors, AWQ, GPTQ, FP8 Checkpoints',
3301
+ sec21R4C1: 'KV Cache Allocation',
3302
+ sec21R4C2: 'Pre-allocates contiguous virtual memory blocks (Contiguous Buffer)',
3303
+ sec21R4C3: 'Partitions KV cache into non-contiguous physical pages (Paged Blocks), cutting memory waste to &lt; 4%',
3304
+ sec21R5C1: 'Batching Strategy',
3305
+ sec21R5C2: 'Static / dynamic micro-batching (optimized for low single-stream latency)',
3306
+ sec21R5C3: 'Continuous batching (iteration-level scheduling) for high concurrent throughput',
3307
+ sec21R6C1: 'Target Hardware Deployment',
3308
+ sec21R6C2: 'Single consumer GPUs (6GB, 8GB, 12GB) or CPU offload machines',
3309
+ sec21R6C3: 'Multi-GPU workstations or datacenter accelerators (RTX 4090, A100, H100)',
3310
+ sec22Title: '2.2 GGUF Quantization Scales & Bits Per Weight (BPW)',
3311
+ sec22P: 'GGUF utilizes K-Quants mixed-precision quantization, dynamically allocating Bits Per Weight (BPW) per layer based on information sensitivity:',
3312
+ sec22Th1: 'Quantization Level',
3313
+ sec22Th2: 'Effective BPW',
3314
+ sec22Th3: 'VRAM Footprint (8B Model)',
3315
+ sec22Th4: 'Perplexity Delta (&Delta;PPL)',
3316
+ sec22Th5: 'Recommended Usage',
3317
+ sec22ChipRec: 'Recommended',
3318
+ sec22R1C5: 'Best value for 6GB and 8GB GPUs, delivering the ideal balance of speed and precision.',
3319
+ sec22R2C5: 'Ideal for 8GB–12GB cards seeking improved multilingual phrasing fidelity.',
3320
+ sec22R3C5: 'Near-lossless FP16 parity, optimal for 12GB+ GPUs like the RTX 4070.',
3321
+ sec22R4C5: 'Golden standard for benchmarking and high-precision evaluation on 16GB+ GPUs.',
3322
+ sec22R5C5: 'Unquantized baseline weights, used for fine-tuning and academic research.',
3323
+ sec23Title: '2.3 Flag Translation Matrix: LM Studio (lms) vs vLLM CLI',
3324
+ sec23P: 'Side-by-side 1:1 CLI flag translation matrix across LM Studio and vLLM runtimes:',
3325
+ sec23Th1: 'Control Function',
3326
+ sec23Th2: 'LM Studio (<code>lms load</code>)',
3327
+ sec23Th3: 'vLLM (<code>python -m vllm.entrypoints.openai.api_server</code>)',
3328
+ sec23R1C1: 'GPU VRAM Offload Ratio',
3329
+ sec23R2C1: 'Context Window Length',
3330
+ sec23R3C1: 'Concurrent Request Slots',
3331
+ sec23R4C1: 'Attention Acceleration',
3332
+ sec23R4C3: 'Enabled automatically (pass <code>--enforce-eager</code> to disable)',
3333
+ sec23R5C1: 'Multi-GPU Tensor Splitting',
3334
+ sec23R6C1: 'KV Cache Quantization',
3335
+
3336
+ sec3Title: '3. CPU Hyper-Threading & SMT Topology Management',
3337
+ sec3Sub: 'Hardware physics: Memory bandwidth ceilings, L1/L2 cache thrashing, and 4-tier thread topology',
3338
+ sec31Title: '3.1 Memory Bandwidth Bottleneck & Compute Bounds',
3339
+ sec31P: 'During autoregressive token generation, generating each single token requires streaming the full model weights across the memory bus exactly once:',
3340
+ sec31MathMain: 'Maximum Tokens/sec &le; Memory Bandwidth (GB/s) &divide; Model Weight Size (GB)',
3341
+ sec31MathSub: 'Theoretical ceiling equation for autoregressive generation speed under memory-bound conditions',
3342
+ sec31P2: 'Real-world bandwidth comparison between System RAM and Dedicated VRAM:',
3343
+ sec31L1: '<strong>Dual-Channel DDR4-3200:</strong> Peak bandwidth ~45–50 GB/s &rarr; Streaming a 4.5 GB model yields at most <strong>10–11 tokens/s</strong>',
3344
+ sec31L2: '<strong>Dual-Channel DDR5-6000:</strong> Peak bandwidth ~85–96 GB/s &rarr; Streaming a 4.5 GB model yields at most <strong>18–21 tokens/s</strong>',
3345
+ sec31L3: '<strong>RTX 3060 GDDR6 (192-bit):</strong> Bandwidth <strong>360 GB/s</strong> &rarr; Streaming a 4.5 GB model delivers <strong>70–80 tokens/s</strong>',
3346
+ sec31L4: '<strong>RTX 4090 GDDR6X (384-bit):</strong> Bandwidth <strong>1,008 GB/s</strong> &rarr; Streaming a 4.5 GB model skyrockets past <strong>150+ tokens/s</strong>',
3347
+ sec32Title: '3.2 SMT / Hyper-Threading Cache Eviction & Pipeline Thrashing',
3348
+ sec32P: 'Simultaneous Multi-Threading (AMD SMT / Intel Hyper-Threading) exposes two logical execution pipelines per physical core that share execution hardware:',
3349
+ sec32Warn: '<strong>Why SMT Slows Down LLM Inference:</strong> LLM matrix multiplications saturate floating-point execution pipelines (AVX2 / AVX-512) at 100%. Squeezing two compute-heavy threads onto one core causes execution port contention and violently <strong>evicts L1/L2 cache lines (Cache Thrashing)</strong>, skyrocketing cache misses and causing generation speeds to <strong>drop by 10% to 25%!</strong>',
3350
+ sec33Title: '3.3 The 4 Thread Allocation Modes in <code>cpuMetrics.js</code>',
3351
+ sec33Th1: 'Mode (htMode)',
3352
+ sec33Th2: 'Thread Count Equation',
3353
+ sec33Th3: 'Behavior & Scheduling Policy',
3354
+ sec33ChipRec: 'Highest Recommendation',
3355
+ sec33R1C3: 'Locks thread count strictly to physical cores, eliminating L1/L2 cache contention to ensure minimal single-stream latency.',
3356
+ sec33R2C3: 'Allocates all virtual threads; ideal for high-throughput multi-client prompt prefilling.',
3357
+ sec33R3C2: 'CPU Architecture Heuristic',
3358
+ sec33R3C3: 'Auto-detects core topology, reserving 1–2 cores for operating system and network I/O overhead.',
3359
+ sec33R4C2: 'Operator Custom Value (1–256)',
3360
+ sec33R4C3: 'Full manual flexibility for system engineers and multi-socket NUMA server architectures.',
3361
+
3362
+ sec4Title: '4. VRAM Footprint Calculation & Multi-GPU Math',
3363
+ sec4Sub: 'Mathematical formulas for model weights, hybrid sliding-window attention, and multi-GPU tensor distribution',
3364
+ sec4MathMain: 'Total VRAM Footprint = Weight Memory + KV Cache Memory + Activation & CUDA Overhead',
3365
+ sec4MathSub: 'Total dedicated video memory budget required prior to model loading',
3366
+ sec41Title: '4.1 Weight Memory Equation & BPW Math',
3367
+ sec41P: 'Static model weight footprint is calculated from total parameters multiplied by Bits Per Weight (BPW) divided by 8:',
3368
+ sec41MathSub: 'Example: Gemma 4 E4B (8.0B parameters) at Q4_K_M (BPW = 4.50) = (8.0 &times; 10&sup9; &times; 4.50) &divide; (8 &times; 1024&sup3;) &asymp; 4.19 GiB (4.50 GB)',
3369
+ sec41P2: 'Fractional Layer Offload Formula:<br><code>Offloaded Weights (GB) = Total Weight Memory &times; (GPU Layers &divide; Total Layers)</code>',
3370
+ sec42Title: '4.2 Hybrid KV Attention Math & Sliding Window (SWA)',
3371
+ sec42P: 'The <strong>Gemma 4</strong> architecture replaces naive full-sequence attention with a <strong>5:1 Hybrid Sliding Window Attention (SWA Profile)</strong>:',
3372
+ sec42L1: '<strong>Local Sliding Layers (5 out of 6 layers):</strong> Cache KV entries only for the latest 1,024 tokens (clamped at 1,024 regardless of whether context is 32K or 64K).',
3373
+ sec42L2: '<strong>Global Layers (1 out of 6 layers):</strong> Retain full context history across the complete context window ($L_{ctx}$).',
3374
+ sec42MathSub: 'H = Attention Heads, D = Head Dimension, B_val = Bytes Per Value per quantization dtype',
3375
+ sec42P2: 'KV Cache Reduction by Data Type (<code>KV_CACHE_DTYPE_BYTES</code>):<br>&bull; <code>fp16</code>: 2.00 Bytes/Val &bull; <code>q8_0</code>: 1.0625 Bytes/Val (~47% reduction) &bull; <code>q4_0</code>: 0.5625 Bytes/Val (~72% reduction)',
3376
+ sec43Title: '4.3 Activation Buffers & CUDA Runtime Overhead',
3377
+ sec43P: 'Scratchpad and activation overhead are calculated via <code>src/lib/vram/estimator.js</code>:',
3378
+ sec43L1: '<strong>CUDA Context:</strong> Driver runtime, unified virtual addressing, and kernel structures consuming 0.35 GB to 0.55 GB.',
3379
+ sec43L2: '<strong>Intermediate Activations:</strong> Tensor activations between transformer blocks, typically 0.15 GB to 0.35 GB (default 0.25 GB).',
3380
+ sec43L3: '<strong>LM Studio Engine Overhead:</strong> Safety buffer of $0.60 \\text{ GB} + 0.10 \\text{ GB} \\times N_{GPUs}$ to prevent Display Driver crashes (TDR).',
3381
+ sec44Title: '4.4 Multi-GPU Tensor Split & Balancing Heuristics',
3382
+ sec44P: 'On multi-GPU rigs, the orchestration system supports two distinct model partitioning strategies:',
3383
+ sec44Th1: 'Strategy',
3384
+ sec44Th2: 'Parameter',
3385
+ sec44Th3: 'Optimal Interconnect',
3386
+ sec44Th4: 'Trade-offs & Constraints',
3387
+ sec44R1C3: 'Standard PCIe Gen3 / Gen4 (No NVLink bridge required)',
3388
+ sec44R1C4: 'Splits model layers sequentially across cards. Ideal for mixed VRAM sizes (e.g. RTX 4080 16GB + RTX 3060 12GB) via <code>--tensor-split 16,12</code>.',
3389
+ sec44R2C3: 'High-speed NVLink bridge or PCIe 4.0 x16',
3390
+ sec44R2C4: 'Horizontally shards weight matrices via Tensor Parallelism for maximum throughput; requires identical GPU models.',
3391
+
3392
+ sec5Title: '5. Zero-Key Local Network Discovery (Zero-Key LAN Discovery)',
3393
+ sec5Sub: 'Automated LAN AI host sweep, deep port fingerprinting, and robust SSRF security perimeter',
3394
+ sec51Title: '5.1 Network Interface Inspection & Concurrency Sweeper',
3395
+ sec51P: 'The <code>scanLan()</code> engine in <code>server/agent/lanDiscovery.js</code> discovers local AI servers autonomously without manual IP inputs or terminal commands:',
3396
+ sec51L1: '<strong>Cross-Platform Interface Inspection:</strong> Baseline extraction via <code>os.networkInterfaces()</code> enriched with Windows PowerShell snapshot or Linux <code>ip -j addr</code> for exact subnet routing.',
3397
+ sec51L2: '<strong>Bounded Concurrency Pool:</strong> TCP connect pre-filtering with bounded concurrency (~64 sockets) sweeping 2,500–3,000 probes in ~15–20 seconds without flooding local home routers.',
3398
+ sec51L3: '<strong>Auto-Sweep Budget Packing:</strong> Sorts candidate LANs smallest-first, cleanly skipping subnets breaching the safety cap (<code>KIKU_LAN_SCAN_MAX_HOSTS = 4096</code>).',
3399
+ sec52Title: '5.2 Probed Ports & Server Fingerprinting',
3400
+ sec52P: 'Every active port undergoes deep HTTP probe fingerprinting to identify engine types and active model catalogs:',
3401
+ sec52Th1: 'Target Port',
3402
+ sec52Th2: 'Expected Engine',
3403
+ sec52Th3: 'Fingerprint Probe Endpoint',
3404
+ sec52Th4: 'Telemetry Returned',
3405
+ sec52R1C4: 'Loading status, quantization, allocated context window',
3406
+ sec52R2C4: 'vLLM version, model architecture, max model len',
3407
+ sec52R3C4: 'Local model tags downloaded in Ollama store',
3408
+ sec52R4C4: 'Round-trip probe latency and active model list',
3409
+ sec53Title: '5.3 SSRF Defense, RFC1918 Pinning & Security Guard',
3410
+ sec53Warn: '<strong>Server-Side Request Forgery (SSRF) Defense:</strong> The LAN discovery module strictly confines scanning targets to <strong>RFC1918 private IPv4 ranges</strong> (<code>10.0.0.0/8</code>, <code>172.16.0.0/12</code>, <code>192.168.0.0/16</code>) and local loopback (<code>127.0.0.1</code>). Public IPs and cloud metadata ranges (<code>169.254.169.254</code>) are immediately rejected, with configuration applying strictly restricted to loopback callers.',
3411
+
3412
+ sec6Title: '6. Model Tuning & Command Encyclopedia (Model Tuning & Commands)',
3413
+ sec6Sub: 'Comprehensive CLI and slash command reference, model load matrices, and sampling hyperparameters',
3414
+ sec6P: 'This section details comprehensive technical controls for the Kiku AI system across Command Line Interfaces (CLI), GPU loading parameters, and sampling hyperparameters.',
3415
+ sec61Title: '6.1 CLI & Interactive Slash Command Encyclopedia',
3416
+ sec61P: 'The system supports both headless one-shot CLI commands and interactive slash commands:',
3417
+ cmd1Desc: 'One-shot headless execution driving the full ReAct agent loop for research, discography lookup, and cron scripts.',
3418
+ cmd2Desc: 'Scans LAN for AI hosts (<code>/lan ifs</code> lists adapters, <code>/lan scan --iface Wi-Fi</code> targets adapter, <code>/lan use 1</code> binds endpoint and persists Base URL).',
3419
+ cmd3Desc: 'Manages loaded models and engine state: adjust temperature (<code>/model temp 0.2</code>), context length (<code>/model ctx 32768</code>), or unload VRAM (<code>/model unload</code>).',
3420
+ cmd4Desc: 'Instantly switch AI providers, supporting <code>lmstudio</code>, <code>vllm</code>, <code>ollama</code>, <code>openai</code>, <code>gemini</code>, <code>groq</code>, <code>deepseek</code>, <code>anthropic</code>, and <code>openrouter</code> with endpoint latency testing.',
3421
+ cmd5Desc: 'Hardware telemetry: monitors real-time VRAM allocation, GPU temperature, bus width, PCIe saturation, and CPU SMT topology.',
3422
+ cmd6Desc: 'Launch 500-case frozen benchmark, open Eval Studio Web Dashboard (Port 3001), run Enterprise 7-Point Model Compatibility probes (<code>npm run eval:compat</code>), or execute security audits.',
3423
+ cmd7Desc: 'Predictive VRAM budgeting: previews KV cache footprints across context lengths to verify GPU fit before loading.',
3424
+ cmd8Desc: 'Model Context Protocol (MCP) bridge: connect to external servers and control the built-in Streamable HTTP server (<code>POST /mcp</code>, Protocol 2025-11-25) supporting 10 AI clients & IDEs (Claude Desktop, Cursor, Windsurf, VS Code, AGY, Cline, Claude Code, Gemini CLI, LibreChat, OpenCode).',
3425
+ cmd9Desc: 'Diagnostics: displays prompt vs generation speed (tok/s) and toggles reasoning model thinking blocks (&lt;think&gt; / Thoughts).',
3426
+ sec62Title: '6.2 Model Load Parameter Matrix (VRAM & CUDA)',
3427
+ sec62P: 'Parameters injected via <code>lms load</code> or <code>POST /api/engine/load</code> to control driver and CUDA kernel behavior:',
3428
+ paramCtxDesc: 'Configures context window size, directly scaling KV cache allocation; higher values demand proportionally more VRAM.',
3429
+ paramGpuDesc: 'GPU layer offload ratio: <code>max</code> for 100% VRAM, <code>off</code> for CPU-only, or float fractions <code>0.0 &ndash; 1.0</code>.',
3430
+ paramHtDesc: 'Controls CPU thread scheduling over SMT. <code>physical</code> locks threads to physical cores, preventing cache contention.',
3431
+ paramFlashDesc: 'Enables FlashAttention-2 tiled attention on high-speed SRAM, slashing memory complexity from O(N&sup2;) to O(N).',
3432
+ paramBatchDesc: '<code>batchSize</code> controls logical prompt batching, while <code>ubatchSize</code> slices chunks into CUDA kernels to prevent memory spikes.',
3433
+ paramSplitDesc: 'Multi-GPU partitioning: <code>layer</code> for cards with asymmetric VRAM, <code>row</code> for paired cards with high-speed interconnect.',
3434
+ paramKvDesc: 'Compresses KV cache. <code>q8_0</code> frees ~50% VRAM with less than 0.2% precision degradation.',
3435
+ sec63Title: '6.3 Inference Sampling Hyperparameters (Logit Post-Processing)',
3436
+ sec63P: 'Parameters governing logit post-processing and sampling, dictating output precision, creativity, and repetition avoidance:',
3437
+ paramTempDesc: 'Logit scaling before Softmax. Recommended <strong>0.2 &ndash; 0.3</strong> for ReAct agent tool calls, or <strong>0.0</strong> for deterministic benchmarks.',
3438
+ paramMinpDesc: 'Cuts candidate tokens falling below dynamic confidence threshold; outperforms legacy <code>top_p</code> on Gemma 4 architectures.',
3439
+ paramToppDesc: 'Nucleus cumulative probability sampling. In Kiku, when <code>min_p</code> is active, <code>top_p</code> auto-relaxes to 1.0 to prevent sampler conflicts.',
3440
+ paramRepeatDesc: 'Penalizes repeated tokens to stop generation loops. Recommended 1.10; values >1.25 risk suppressing valid grammatical syntax.',
3441
+ paramTokensDesc: 'Upper ceiling on tokens generated per reply. Kiku reserves an 8,192 token buffer for detailed responses.',
3442
+ sec64Title: '6.4 REST API Reference &amp; Code Playbook',
3443
+ sec64P: 'Copyable cURL examples and Node.js snippets for programmatic automation of the Inference Control Center:',
3444
+ sec64Api1Title: '1. Query Hardware Telemetry (GPU, VRAM, and CPU SMT)',
3445
+ sec64Api2Title: '2. Load Model into VRAM with Hyper-Threading and FlashAttention',
3446
+ sec64Api3Title: '3. Node.js Automation Script for Model Loading',
3447
+ sec64Api4Title: '4. Free Video Memory (Unload Model)',
3448
+
3449
+ sec7Title: '7. Hardware Tuning Playbook & OOM Recovery (Tuning Playbook & OOM)',
3450
+ sec7Sub: 'VRAM tier configuration matrices, 4-step OOM recovery ladder, and PCIe bus speed warnings',
3451
+ sec71Title: '7.1 Hardware VRAM Tiers Matrix',
3452
+ sec71P: 'Hardware tier matrix calibrated for maximal generation tokens/sec without VRAM overflow:',
3453
+ sec71Th1: 'VRAM Capacity',
3454
+ sec71Th2: 'Recommended Model &amp; Quantization',
3455
+ sec71Th3: 'Context &amp; KV Settings',
3456
+ sec71Th4: 'CPU SMT Mode',
3457
+ sec71R1C3: 'Context <strong>16,384</strong> (16K), KV Cache: <code>q4_0</code>, FlashAttn: Enabled',
3458
+ sec71R2C3: 'Context <strong>32,768</strong> (32K), KV Cache: <code>q8_0</code>, FlashAttn: Enabled',
3459
+ sec71R3C3: 'Context <strong>32,768 &ndash; 65,536</strong>, KV Cache: <code>q8_0</code> or <code>fp16</code>',
3460
+ sec71R4C3: 'Context <strong>65,536+</strong>, Multi-GPU Split: <code>layer</code> or <code>row</code>',
3461
+ sec72Title: '7.2 4-Step Deterministic Out-Of-Memory (OOM) Recovery',
3462
+ sec72P: 'If the VRAM bar shows red (>90%) or the driver logs <code>CUDA Out of Memory</code>, follow this 4-step deterministic ladder to recover without rebooting:',
3463
+ sec72Step1: '<strong>Step 1: Compress KV Cache to <code>q8_0</code> or <code>q4_0</code></strong><br>Immediately shrinks KV cache by 47% to 72%, freeing 1.2 to 2.5 GB of VRAM without reducing context length.',
3464
+ sec72Step2: '<strong>Step 2: Step Down Context Length by One Tier</strong><br>Drop from 32,768 to 16,384 (16K) or 8,192 (8K), sufficient for 95% of real-world chat and retrieval.',
3465
+ sec72Step3: '<strong>Step 3: Verify and Enable <code>flashAttn = true</code></strong><br>Ensures FlashAttention-2 is active, eliminating quadratic memory expansion during prompt prefill.',
3466
+ sec72Step4: '<strong>Step 4: Set <code>gpuOffload</code> to a Decimal Fraction (e.g. <code>0.85</code>)</strong><br>Offload the top 15% of layers to system RAM instead of forcing full GPU placement.',
3467
+ sec73Title: '7.3 PCIe Bandwidth &amp; Partial Offloading Warning',
3468
+ sec73P: 'Critical partial offload warning: PCIe Gen3 x16 bus bandwidth peaks at only <strong>~15.75 GB/s</strong>, which is 25 to 60 times slower than onboard VRAM!',
3469
+ sec73Warn: '<strong>PCIe Thrashing Bottleneck Warning:</strong> If even 2–3 layers spill into System RAM, intermediate layer activations must cross the PCIe bus on every single token, causing generation speeds to plunge from 70 tokens/s to <strong>8–12 tokens/s</strong>. Always pick a quantization tier that fits <em>100% into VRAM</em>.'
3470
+ }
3471
+ };
3472
+
3473
+ let liveHwCached = null;
3474
+
3475
+ function updateHwMeta() {
3476
+ const meta = document.getElementById('hw-banner-meta');
3477
+ if (!meta) return;
3478
+ const lang = localStorage.getItem('kiku_lang') || 'th';
3479
+ if (!liveHwCached) {
3480
+ const dict = DOCS_I18N[lang] || DOCS_I18N.th;
3481
+ if (dict.hwBannerMeta) meta.textContent = dict.hwBannerMeta;
3482
+ return;
3483
+ }
3484
+ const gpu = liveHwCached.gpu || {};
3485
+ const cpu = liveHwCached.cpu || {};
3486
+ if (lang === 'zh') {
3487
+ meta.textContent = '已检测到 ' + (gpu.name || 'iGPU') + ' 与 ' + (cpu.model || 'CPU') + ' • 硬件遥测就绪，可供调优';
3488
+ } else if (lang === 'en') {
3489
+ meta.textContent = 'Detected ' + (gpu.name || 'iGPU') + ' with ' + (cpu.model || 'CPU') + ' • Telemetry ready for tuning';
3490
+ } else {
3491
+ meta.textContent = 'ตรวจพบ ' + (gpu.name || 'iGPU') + ' พร้อม ' + (cpu.model || 'CPU') + ' • ข้อมูลพร้อมสำหรับการปรับจูน';
3492
+ }
3493
+ }
3494
+
3495
+ function toggleLanguage() {
3496
+ const current = localStorage.getItem('kiku_lang') || 'th';
3497
+ const next = current === 'th' ? 'zh' : (current === 'zh' ? 'en' : 'th');
3498
+ applyLanguage(next);
3499
+ }
3500
+
3501
+ function applyLanguage(lang) {
3502
+ localStorage.setItem('kiku_lang', lang);
3503
+ document.documentElement.lang = lang === 'zh' ? 'zh-CN' : (lang === 'en' ? 'en' : 'th');
3504
+ const btn = document.getElementById('btn-lang');
3505
+ if (btn) btn.textContent = lang === 'th' ? 'TH' : (lang === 'zh' ? '中文' : 'EN');
3506
+
3507
+ const dict = DOCS_I18N[lang] || DOCS_I18N.th;
3508
+ document.querySelectorAll('[data-i18n]').forEach(el => {
3509
+ const key = el.getAttribute('data-i18n');
3510
+ if (dict && dict[key] !== undefined) {
3511
+ if (typeof dict[key] === 'string' && dict[key].includes('<')) {
3512
+ el.innerHTML = dict[key];
3513
+ } else {
3514
+ el.textContent = dict[key];
3515
+ }
3516
+ }
3517
+ });
3518
+ updateHwMeta();
3519
+ }
3520
+
3521
+ // Fetch Live Hardware
3522
+ async function loadLiveHardware() {
3523
+ try {
3524
+ const res = await fetch('/api/v1/system/hardware');
3525
+ if (!res.ok) return;
3526
+ const json = await res.json();
3527
+ liveHwCached = json.data || {};
3528
+ const gpu = liveHwCached.gpu || {};
3529
+ const cpu = liveHwCached.cpu || {};
3530
+
3531
+ const chipGpu = document.getElementById('chip-gpu');
3532
+ const chipVram = document.getElementById('chip-vram');
3533
+ const chipCpu = document.getElementById('chip-cpu');
3534
+ const chipSmt = document.getElementById('chip-smt');
3535
+
3536
+ if (gpu.name && chipGpu) chipGpu.textContent = 'GPU: ' + gpu.name;
3537
+ if (gpu.vramTotalMb && chipVram) chipVram.textContent = 'VRAM: ' + (gpu.vramTotalMb / 1024).toFixed(1) + ' GB';
3538
+ if (cpu.model && chipCpu) chipCpu.textContent = 'CPU: ' + (cpu.model || 'Unknown');
3539
+ if (cpu.statusText && chipSmt) chipSmt.textContent = 'SMT: ' + cpu.statusText;
3540
+
3541
+ updateHwMeta();
3542
+ } catch {}
3543
+ }
3544
+
3545
+ // Init
3546
+ document.addEventListener('DOMContentLoaded', () => {
3547
+ const savedTheme = localStorage.getItem('kiku_theme') || 'dark';
3548
+ document.documentElement.setAttribute('data-theme', savedTheme);
3549
+ const savedLang = localStorage.getItem('kiku_lang') || 'th';
3550
+ applyLanguage(savedLang);
3551
+ loadLiveHardware();
3552
+ initScrollSpy();
3553
+ initScrollTop();
3554
+ });
3555
+ </script>
3556
+ </body>
3557
+ </html>`;
3558
+ }