Hub AI
Repo ai là hub AI của mỗi stack. ai-gateway (LiteLLM) với alias, key và ngân sách theo ngày, ai-models cho chuyển giọng nói thành văn bản, embedding ảnh và khung hình video, upstream OpenRouter, và cách đổi mô hình, ngân sách hay alias.
Tìm kiếm hỏi một mô hình ngôn ngữ xem câu truy vấn có nghĩa gì, một lượt đọc tin biến video hay ảnh của người bán thành bản nháp, còn tìm bằng ảnh so sánh embedding của chữ và ảnh. Trên cluster, không bên gọi nào tự gọi nhà cung cấp mô hình. Mỗi stack chạy hub AI từ repo ai (shopnexus/ai): ai-gateway, một proxy LiteLLM có API tương thích OpenAI, và ai-models, service Go chứa các mô hình ShopNexus tự host. Bản thiết kế nằm ở docs/superpowers/specs/2026-11-17-ai-hub-design.md.
Bên gọi là server và console agent. Mỗi bên nêu một mục đích, tức một alias như search, và giữ một virtual key cho mỗi mục đích, kèm ngân sách theo ngày. Mỗi stack có gateway, key và ngân sách riêng, nên một vòng lặp ở dev không thể tiêu hết phần của prod.
| Alias | Upstream | Mô hình | Dùng cho |
|---|---|---|---|
search | OpenRouter | anthropic/claude-haiku-5.5 | đọc câu truy vấn tìm kiếm |
listing-read | OpenRouter | anthropic/claude-haiku-5.5 | đọc khung hình và lời nói trong video, một tấm ảnh, hoặc tin Chợ Tốt của người bán thành bản nháp |
scam-check | OpenRouter | anthropic/claude-haiku-5.5 | kiểm tra một khung chat xem có lừa đảo không |
console-agent | OpenRouter | anthropic/claude-sonnet-5.5 | console agent |
embed-text | OpenRouter, chỉ DeepInfra | baai/bge-m3, 1024 chiều | vector chữ của tin đăng và câu truy vấn |
embed-image | ai-models | siglip2-so400m-patch16-384, 1152 chiều | vector ảnh, và các đoạn chữ tiếng Anh ngắn cho text tower của SigLIP |
stt | ai-models | gipformer-1.5 | chuyển giọng nói thành văn bản khi đọc video |
Mỗi alias là một mục của gateway.aliases trong chart/values.yaml của repo ai. Đổi mô hình đứng sau một alias không cần image server mới.
Triển khai
Repo ai có một Helm chart trong chart/. Repo tổng triển khai nó một lần cho mỗi stack bằng hai Application của Argo CD trong infra/argocd/ai.yaml: ai-dev vào shopnexus-dev và ai-prod vào shopnexus-prod. Mỗi Application có một nguồn, chart/ của repo ai, ai-dev ở nhánh main và ai-prod ở commit ai của bản phát hành của repo tổng, và đặt values riêng của stack ngay trong spec.source.helm.valuesObject. root tạo chúng ở wave 2, sau các Application của stack ở wave 1, vì Postgres của stack chứa database của gateway và secret đã seal của stack chứa các key.
flowchart TB
app["Application ai-dev<br/>repo shopnexus/ai, chart/, main<br/>+ valuesObject trong infra/argocd/ai.yaml"]
app -->|wave 0| gw["Deployment và Service ai-gateway<br/>ghcr.io/berriai/litellm-database:v1.108.0<br/>ConfigMap ai-gateway-config"]
app -->|wave 0| models["Deployment và Service ai-models<br/>ghcr.io/shopnexus/ai"]
app -->|"wave 1, Sync hook"| job["Job ai-gateway-keys<br/>curlimages/curl"]
gw --> db[("postgres-rw<br/>database litellm")]| Values | Nằm ở | Chứa |
|---|---|---|
| lựa chọn của hub | chart/values.yaml trong repo ai | các alias và mô hình của chúng, các image, các key và alias mỗi key được gọi, thiết lập của ai-models |
| của stack | valuesObject của ai-<stack> trong infra/argocd/ai.yaml | stack, dailyUnits và tpmLimit hoặc rpmLimit của mọi key, models.embedModels, models.memoryRequest và models.memoryLimit |
Chart từ chối render khi thiếu values của stack. Image Updater dời image ai-models trên ai-dev theo digest của :main. Trên ai-prod, workflow Release của repo tổng ghi commit ai và images.models.tag (Phát hành). Một thay đổi ở chart hay ở chart/values.yaml tới dev ngay khi nó nằm trên main của repo ai, và tới prod cùng bản phát hành tiếp theo.
Đường đi của request
flowchart LR
server["pod server<br/>LLM_MODEL=search"] -->|"POST /v1/chat/completions<br/>Bearer LLM_API_KEY"| gw["ai-gateway:4000<br/>alias search"]
gw -->|"kiểm tra key, ngân sách, tpm"| db[("Postgres<br/>database litellm")]
gw -->|"openai/anthropic/claude-haiku-5.5<br/>Bearer OPENROUTER_API_KEY"| or["OpenRouter<br/>openrouter.ai/api/v1"]flowchart LR server["pod server<br/>module assist"] -->|"POST /v1/video/frames<br/>không key"| models["ai-models:8000<br/>ffmpeg, khung hình, Gipformer"] server -->|"POST /v1/audio/transcriptions, model stt<br/>Bearer STT_API_KEY"| gw["ai-gateway:4000<br/>alias stt, listing-read"] server -->|"POST /v1/chat/completions, model listing-read<br/>Bearer ASSIST_LLM_API_KEY"| gw gw -->|"openai/gipformer-1.5<br/>không key"| models gw -->|"openai/anthropic/claude-haiku-5.5<br/>Bearer OPENROUTER_API_KEY"| or["OpenRouter"]
flowchart LR
server["pod server<br/>EMBED_TEXT_MODEL=embed-text<br/>EMBED_IMAGE_MODEL=embed-image"] -->|"POST /v1/embeddings<br/>Bearer EMBED_INDEX_API_KEY hoặc EMBED_SEARCH_API_KEY"| gw["ai-gateway:4000<br/>alias embed-text, embed-image"]
gw -->|"kiểm tra key, ngân sách, rpm"| db[("Postgres<br/>database litellm")]
gw -->|"openai/baai/bge-m3, provider DeepInfra<br/>Bearer OPENROUTER_API_KEY"| or["OpenRouter"]
gw -->|"openai/siglip2-so400m-patch16-384<br/>không key"| models["ai-models:8000<br/>SigLIP 2"]ConfigMap server-env của server (infra/stack/templates/_server-env.tpl) trỏ mọi thiết lập mô hình vào hub:
LLM_BASE_URL: http://ai-gateway:4000/v1
LLM_MODEL: search
ASSIST_LLM_BASE_URL: http://ai-gateway:4000/v1
ASSIST_LLM_MODEL: listing-read
TRUST_LLM_BASE_URL: http://ai-gateway:4000/v1
TRUST_LLM_MODEL: scam-check
STT_BASE_URL: http://ai-gateway:4000/v1
STT_MODEL: stt
AI_FRAMES_BASE_URL: http://ai-models:8000/v1
EMBED_TEXT_BASE_URL: http://ai-gateway:4000/v1
EMBED_IMAGE_BASE_URL: http://ai-gateway:4000/v1
EMBED_TEXT_MODEL: embed-text
EMBED_IMAGE_MODEL: embed-image
EMBED_TEXT_VERSION: bge-m3@5617a9f61b028005a4858fdac845db406aefb181
EMBED_IMAGE_VERSION: siglip2-so400m-patch16-384@29f74e673c298fd07482d8e20138179282001eb7-fp32Console agent nhận LITELLM_BASE_URL=http://ai-gateway:4000/v1 và AGENT_MODEL_ID=console-agent. Server tự gọi /v1/video/frames của ai-models, vì LiteLLM chỉ định tuyến API của OpenAI. Tên Service ai-gateway và ai-models được phân giải trong chính namespace của stack, nên server dev gọi tới hub của dev và server prod gọi tới hub của prod.
Alias và cấu hình gateway
Các alias trong chart/values.yaml, ở đây là search và embed-text:
gateway:
secret: litellm-secrets
database: { host: postgres-rw, name: litellm, user: litellm, passwordSecret: litellm-db }
aliases:
search:
model: openai/anthropic/claude-haiku-5.5
apiBase: https://openrouter.ai/api/v1
apiKeySecret: OPENROUTER_API_KEY
price: token
embed-text:
model: openai/baai/bge-m3
apiBase: https://openrouter.ai/api/v1
apiKeySecret: OPENROUTER_API_KEY
mode: embedding
price: token
extraBody: { provider: { order: [DeepInfra], allow_fallbacks: false } }Chart render mỗi alias thành một mục model_list trong ConfigMap ai-gateway-config. Mục search và các thiết lập chung ra như sau:
model_list:
- model_name: search
litellm_params:
model: openai/anthropic/claude-haiku-5.5
api_base: https://openrouter.ai/api/v1
api_key: os.environ/OPENROUTER_API_KEY
model_info:
input_cost_per_token: 0.000001
output_cost_per_token: 0.000001
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
store_prompts_in_spend_logs: false
maximum_spend_logs_retention_period: 30d
litellm_settings:
drop_params: trueTiền tố openai/ báo LiteLLM nói API của OpenAI với api_base. Alias có apiKeySecret gửi key đó của litellm-secrets; alias không có nó gửi api_key: none, dành cho ai-models, vốn không có xác thực. extraBody tới upstream dưới dạng extra_body. drop_params: true khiến LiteLLM bỏ các trường request mà upstream không nhận. NetworkPolicy của stack để egress mở, nên ai-gateway gọi được tới OpenRouter.
store_prompts_in_spend_logs: false giữ body của request, trong đó có ảnh của tìm bằng ảnh, ngoài spend log của LiteLLM, và spend log được giữ 30 ngày. infra/probes/litellm-embed/run.sh đo điều này trên LiteLLM v1.108.0 với một upstream giả ngày 2026-11-10: data URL 706 kB và 1,72 MB tới upstream nguyên vẹn, ba lời gọi tốn 0,001728 (mỗi lời gọi 576 token, tính theo usage của upstream), và không dòng nào trong ba dòng spend log chứa input.
OpenRouter
Mọi alias trừ embed-image và stt đi tới OpenRouter bằng OPENROUTER_API_KEY của stack, mỗi stack một key. Hãy đặt cho key đó một hạn mức credit theo ngày trên OpenRouter; đó là chốt chặn cuối sau ngân sách của chính gateway. Các số đo qua LiteLLM v1.108.0 ngày 2026-11-17:
- LiteLLM chuyển nguyên
usagecủa OpenRouter (token vàcost) cho chat và embedding, nên ngân sách đếm đúng số token OpenRouter báo. - Mã 402 của upstream, câu trả lời của OpenRouter khi credit của key đã hết, tới bên gọi dưới dạng HTTP 402 với code
"402". - OpenRouter phục vụ
baai/bge-m3từ hai provider. DeepInfra (fp32) cho các vector của TEI mà các stack từng chạy với cosine 0,999999 trên mọi văn bản tham chiếu dưới 2048 token (ai/embed/testdata/bge-m3-reference.json); Parasail cho 0,996.embed-textghim DeepInfra vớiallow_fallbacks: false, nên vector đã lưu và vector mới nằm trong cùng một không gian. LiteLLM chuyển tiếp lệnh ghim: ghim Parasail qua nó cho ra vector của Parasail. - 16 input trong một request
embed-textmất 2,3 giây.
Mô hình ngân sách
Ngân sách của LiteLLM tính bằng tiền, và price của mỗi alias quyết định số tiền đó đại diện cho gì:
price | Giá | 1 đơn vị ngân sách là |
|---|---|---|
token | 0.000001 mỗi token, cả input lẫn output | 1.000.000 token |
second | 0.000001 mỗi giây audio | 1.000.000 giây |
usd | giá niêm yết của mô hình, inputCostPerToken và outputCostPerToken | 1 USD |
console-agent được tính theo giá 2 và 10 USD cho mỗi 1 triệu token vào và ra. dailyUnits của một key tính bằng phần triệu đơn vị của các alias của nó, và chart chia nó cho 1.000.000 để ra max_budget. Chart từ chối một key gồm các alias tính giá theo đơn vị khác nhau.
| Key | Secret | Alias | dailyUnits dev | giới hạn dev | dailyUnits prod | giới hạn prod |
|---|---|---|---|---|---|---|
server-llm | server-secrets LLM_API_KEY | search | 200.000 token | 20.000 tpm | 2.000.000 token | 100.000 tpm |
server-stt | server-secrets STT_API_KEY | stt | 3.600 giây | 10 rpm | 36.000 giây | 60 rpm |
server-assist | server-secrets ASSIST_LLM_API_KEY | listing-read | 1.200.000 token | 60.000 tpm | 12.000.000 token | 300.000 tpm |
server-trust | server-secrets TRUST_LLM_API_KEY | scam-check | 600.000 token | 30.000 tpm | 6.000.000 token | 150.000 tpm |
server-embed-index | server-secrets EMBED_INDEX_API_KEY | embed-text, embed-image | 10.000.000 token | 120 rpm | 50.000.000 token | 600 rpm |
server-embed-search | server-secrets EMBED_SEARCH_API_KEY | embed-text, embed-image | 1.000.000 token | 60 rpm | 10.000.000 token | 600 rpm |
agent | agent-secrets AGENT_LLM_API_KEY | console-agent | 20 USD | 100.000 tpm | 20 USD | 200.000 tpm |
chart/values.yaml đặt 20 USD mỗi ngày của agent cho mọi stack; infra/argocd/ai.yaml đặt phần còn lại. LiteLLM reset mức chi của mỗi key hằng ngày, với budget_duration: 1d.
Server index tin đăng bằng server-embed-index và embed câu truy vấn bằng server-embed-search. Một lần backfill toàn bộ tin đăng tiêu key index, còn tìm bằng ảnh giữ ngân sách riêng. ai-models tính mỗi ảnh 576 token, tức 24 × 24 patch, và mỗi đoạn chữ theo số token của nó; LiteLLM tính giá theo usage đó. Một tin 10 ảnh tốn khoảng 5.800 token, nên ngân sách index của dev đủ cho khoảng 1.700 tin mỗi ngày.
Một lượt đọc video gửi cho listing-read 8 khung hình 768 px, danh sách danh mục con và lời nói đã chép, khoảng 5.500 token, nên ngân sách dev đủ cho khoảng 200 lượt mỗi ngày và prod khoảng 2.000 lượt. Một lượt đọc ảnh gửi một tấm ảnh, khoảng 1.500 token; mỗi tài khoản được bắt đầu 30 lượt đọc video, 60 lượt đọc ảnh và 30 lượt đọc link mỗi ngày. Một lần kiểm tra lừa đảo gửi prompt và 20 tin nhắn ngắn, khoảng 1.300 token, nên dev đủ cho khoảng 460 lần mỗi ngày và prod khoảng 4.600 lần.
Một lần thử trên cluster k3d cục bộ đặt ngân sách 60 token cho key tìm kiếm: khi tiêu hết, các lời gọi thất bại với HTTP 422 và Budget has been exceeded, còn lời gọi tới một alias ngoài models của key nhận 403. Một lần thử trên LiteLLM v1.108.0 gửi 5,55 giây audio, và mức chi của server-stt tăng 0,00000555. LiteLLM hỏi ai-models định dạng verbose_json khi bên gọi không nêu response_format, và tính giá mỗi lời gọi giọng nói theo trường duration mà câu trả lời json và verbose_json mang theo. Câu trả lời text không có duration và có giá 0, nên server không được hỏi text.
Job tạo key
Các key được tạo bởi Job ai-gateway-keys, một Sync hook của Argo CD ở wave 1 của ai-<stack>, sau khi ai-gateway (wave 0) sẵn sàng. chart/templates/gateway-keys.yaml render nó từ gateway.keys. Pod của nó chạy curlimages/curl và làm như sau cho từng key:
flowchart TD start["Sync hook ai-gateway-keys"] --> update["POST /key/update<br/>key = giá trị của key trong Secret của nó"] update -->|200| ok["log: key server-llm: HTTP 200"] update -->|not 200| generate["POST /key/generate<br/>cùng giá trị key"] generate -->|200| ok generate -->|not 200| fail["log mã trạng thái và message<br/>exit 1, thử lại tối đa 10 lần"]
Hai lời gọi gửi cùng một body: giá trị của key lấy từ Secret mà trường secret của key ghi, key_alias (tên key), models, max_budget, budget_duration: 1d, và tpm_limit hoặc rpm_limit. Chúng xác thực bằng master key trong litellm-secrets. Một lần sync thành công ghi một dòng key <tên>: HTTP 200 cho mỗi key, tổng cộng bảy dòng.
Giá trị của các key được cố định từ trước: lệnh seal sinh chúng rồi seal vào server-secrets và agent-secrets, và Job ghi đúng các giá trị đó vào LiteLLM. Chạy Job hai lần cho cùng một kết quả. Khi mất database của gateway, lời gọi update thất bại, lời gọi generate tạo lại key với giá trị bên gọi đang giữ, và bên gọi không phải khởi động lại. Một key đổi tên trong gateway.keys vẫn giữ giá trị, nên /key/update của lần sync sau tìm thấy nó theo giá trị và đổi alias; trên v1.108.0 ngày 2026-11-10, key được đổi tên giữ nguyên mức chi.
Câu trả lời của LiteLLM chứa key, nên Job chỉ log mã HTTP. Khi thất bại, nó in thêm trường message của câu trả lời.
kubectl -n shopnexus-dev logs job/ai-gateway-keysargocd.argoproj.io/hook-delete-policy: BeforeHookCreation giữ Job của lần chạy trước cho tới khi lần sync sau thay nó.
Database của gateway
LiteLLM lưu key và mức chi trong Postgres, ở một database riêng trên cluster CNPG postgres của stack. Chart của stack tạo database đó, vì Postgres thuộc về stack:
postgres.yamltronginfra/stackkhai báo một managed rolelitellmlấy mật khẩu từ Secretlitellm-db, và mộtDatabasecủa CNPG tênlitellmdo role đó sở hữu (wave 1 của stack).ai-gatewayghépDATABASE_URL=postgresql://litellm:$(DB_PASSWORD)@postgres-rw:5432/litellmtừgateway.database.- Image là
ghcr.io/berriai/litellm-database:v1.108.0, bản LiteLLM có dùng database.
Dữ liệu của server nằm trong database app của cùng cluster. Role litellm chỉ sở hữu litellm.
Secret
go -C infra run ./cmd/seal <stack> sinh mọi giá trị dưới đây trừ OPENROUTER_API_KEY vào file infra/stack/secrets/<stack>.env (đã bị git bỏ qua). Bạn tự ghi OPENROUTER_API_KEY, và lệnh seal dừng với set OPENROUTER_API_KEY cho tới khi bạn ghi. Tên Secret litellm-secrets và litellm-db giữ như trước khi có hub.
Giá trị trong <stack>.env | Seal vào | Ai đọc |
|---|---|---|
LITELLM_MASTER_KEY | litellm-secrets | ai-gateway, Job ai-gateway-keys, bạn trong admin UI |
OPENROUTER_API_KEY | litellm-secrets | ai-gateway, khi gọi OpenRouter |
LITELLM_DB_PASSWORD | litellm-db (basic-auth), khóa password | CNPG cho role, ai-gateway cho DATABASE_URL |
LLM_API_KEY, STT_API_KEY, ASSIST_LLM_API_KEY, TRUST_LLM_API_KEY, EMBED_INDEX_API_KEY, EMBED_SEARCH_API_KEY | server-secrets | server; Job ai-gateway-keys |
AGENT_LLM_API_KEY | agent-secrets | console agent; Job ai-gateway-keys |
ai-gateway thuộc một Application khác với secret của stack và không mang checksum của chúng. Sau khi seal lại litellm-secrets hay litellm-db, khởi động lại nó bằng tay:
kubectl -n shopnexus-dev rollout restart deploy/ai-gatewayMột key chart có nêu mà Secret của nó không có khiến pod ai-gateway-keys không khởi động được, và lần sync ai-<stack> dừng ở wave 1: seal lại và push secret trước khi commit ai thêm key tới main. Secret mô tả cách lệnh seal và controller seal chúng.
Khi hết ngân sách
Gateway từ chối một key đã tiêu hết bằng HTTP 422 và Budget has been exceeded. Khi credit OpenRouter của stack đã hết, nó chuyển nguyên mã 402 của OpenRouter. Client LLM của server coi 402 như 429, một lỗi tạm thời, và client embed của nó thử lại. isBudgetError của console agent coi 402 là hết ngân sách, như với budget_exceeded của chính LiteLLM.
Tìm kiếm của server không hỏng khi mô hình hỏng. Search trong server/internal/discovery/service/search.go cho mô hình 4 giây. Gặp bất kỳ lỗi nào, kể cả bị từ chối vì hết ngân sách hay vượt giới hạn tốc độ, nó ghi log mức warn the model did not read the query kèm lỗi, rồi tìm bằng đúng những từ người dùng gõ.
sequenceDiagram participant App as app participant S as server participant G as ai-gateway App->>S: GET /v1/search?q=... S->>S: tra cache (7 ngày) S->>G: chat/completions, model search G-->>S: 422 Budget has been exceeded, hoặc 402 S->>S: log "the model did not read the query" S->>S: tìm các từ gốc như một cụm S-->>App: 200, danh sách tin, không có chip
Người dùng vẫn nhận một trang tin đăng, khớp theo các từ họ đã gõ. Trang không có chip, và không có các boost về danh mục, giá, nơi chốn hay độ mới mà mô hình lẽ ra đọc ra từ câu truy vấn. Một câu truy vấn mô hình đã đọc trong 7 ngày qua được lấy từ cache của server và giữ nguyên phần hiểu của nó. Lỗi của server khi câu trả lời khác 200 là model answered <status>, nên hết ngân sách ghi model answered 422 và hết credit ghi model answered 402.
Lời gọi vượt giới hạn token mỗi phút cũng lỗi, và tìm kiếm quay về các từ gốc cho tới khi sang phút mới. Tìm kiếm và khám phá liệt kê các boost mà mô hình có thể đặt.
ai-models
ai-models gồm một Deployment và một Service ở cổng 8000, không có Ingress và không có xác thực; from-stack cho các pod của stack đi vào. Alias stt và embed-image của gateway gọi nó, còn server gọi thẳng route khung hình của nó. Thiết lập của nó là models.* trong chart/values.yaml.
Chuyển giọng nói thành văn bản
ai-models phục vụ POST /v1/audio/transcriptions của OpenAI bằng Gipformer 1.5, một mô hình tiếng Việt 68,6 triệu tham số, chạy trên CPU. Nó nhận mọi file audio hay video mà ffmpeg đọc được, tối đa 100 MB và 300 giây audio (models.maxUploadMB, models.maxAudioSeconds). Silero VAD cắt phần có tiếng nói tại các khoảng lặng thành các đoạn dài tối đa 20 giây, và câu trả lời là văn bản chữ thường, không dấu câu. Mỗi lúc có hai request được giải mã (models.maxConcurrent), các request khác chờ.
Server gọi stt khi đọc video của người bán (module assist). Nó xin response_format: json, nên LiteLLM tính giá lời gọi theo duration.
Để chuyển stt sang nhà cung cấp khác, đặt gateway.aliases.stt.model là chuỗi mô hình LiteLLM của nhà cung cấp đó, ví dụ groq/whisper-large-v3, và gateway.aliases.stt.apiBase là base URL của họ; thêm key của nhà cung cấp vào litellm-secrets và ghi tên nó vào gateway.aliases.stt.apiKeySecret. Server vẫn hỏi stt như cũ.
ai-models ghi một dòng log cho mỗi request, không kèm nội dung transcript:
kubectl -n shopnexus-dev logs deploy/ai-modelsKhung hình video
POST /v1/video/frames không phải route của OpenAI, nên server gọi nó ở AI_FRAMES_BASE_URL, không có key, và gateway không tính gì cho nó. Nó nhận video dài 3 đến 35 giây (models.framesMaxSeconds), giải mã 2 khung mỗi giây với cạnh dài tối đa 1600 px, bỏ các khung có phương sai Laplacian dưới models.framesMinSharpness và các khung lặp lại khung khác, rồi trả về tối đa 8 ảnh JPEG rải đều trên video. Mỗi lúc có hai request cắt khung (models.framesMaxConcurrent), ngoài hai request giải mã giọng nói. Ngày 2026-11-10, hai request cắt khung của một video 1080p dài 30 giây và hai request chép lời cùng lúc đưa pod lên 2,42 GiB.
Embedding ảnh
ai-models phục vụ POST /v1/embeddings bằng SigLIP 2 (siglip2-so400m-patch16-384, ONNX fp32, 1152 chiều) khi models.embedModels ghi tên nó. Input bắt đầu bằng data:image/ là ảnh; mọi input khác là chữ cho text tower của SigLIP. Weights nặng 4,5 GB. Khi models.embedModels rỗng, ai-models không nạp SigLIP 2, và /v1/embeddings trả 404 model_not_found.
| Stack | models.embedModels | Bộ nhớ xin, giới hạn | Số đo |
|---|---|---|---|
| dev | rỗng | 2Gi, 3Gi | chỉ giọng nói và khung hình đạt đỉnh 2,42 GiB ngày 2026-11-10 |
| prod | siglip2-so400m-patch16-384=/models/siglip2-so400m-patch16-384 | 6Gi, 8Gi | 4,0 GiB lúc rảnh và 5,3 GiB với 16 ảnh, ngày 2026-11-10 |
Dev không nạp SigLIP 2 vì máy dev không còn chỗ cho nó (2026-11-17). Values của stack dev đặt server.embed.image: false, nên server không ghi và không truy vấn vector ảnh ở đó. infra/check.sh báo lỗi khi vector ảnh của một stack bật mà ai-models của nó không có SigLIP 2, hoặc tắt mà có.
Vector và version của chúng
Server lưu EMBED_TEXT_VERSION và EMBED_IMAGE_VERSION cùng mỗi vector. Cả hai nằm trong infra/stack/env/server.env, file mà chart của cluster và docker-compose.yml ở gốc cùng đọc. Một mô hình mới cần một version mới trong cùng thay đổi: server khi đó coi các vector đã lưu là thiếu, và go run ./cmd/search-reindex -every 2s trong server embed lại mọi tin đăng, mỗi 2 giây một tin.
EMBED_TEXT_VERSION giữ nguyên bge-m3@5617a9f61b028005a4858fdac845db406aefb181 khi embed-text chuyển từ TEI sang OpenRouter, vì vector của DeepInfra khớp. Một văn bản dài hơn 2048 token cho cosine 0,90, vì TEI cắt input ở 2048 token còn OpenRouter thì không. Server cắt chữ của tin đăng ở 2.000 ký tự (EmbeddingTextMax), dưới 2048 token.
Mỗi loại vector có thể tắt. server.embed.text và server.embed.image trong values của stack bật hay tắt nó, và một loại bị tắt nhận EMBED_*_MODEL, EMBED_*_BASE_URL và EMBED_*_VERSION rỗng. Server khi đó không ghi vector loại đó và bỏ danh sách của nó khỏi tìm kiếm; BM25 luôn chạy. Tìm photo khi vector ảnh tắt trả 503 search_unavailable.
Stack cục bộ
docker-compose.yml ở gốc chạy ai-models-dev ở 127.0.0.1:56491 và ai-models-prod ở 127.0.0.1:56490, không có gateway và không có TEI. Server gọi thẳng ai-models-<stack> cho vector ảnh, giọng nói và khung hình, và gọi mô hình là siglip2-so400m-patch16-384; ai-models không cần key và bỏ qua key được gửi. Với vector chữ, nó đọc EMBED_TEXT_BASE_URL, EMBED_TEXT_MODEL, EMBED_INDEX_API_KEY và EMBED_SEARCH_API_KEY từ server/.env: baai/bge-m3 của OpenRouter với khóa OpenRouter của bạn, hoặc EMBED_TEXT_MODEL rỗng, tức tắt vector chữ. infra/check.sh báo lỗi khi các thiết lập AI_* của file compose khác models.* trong chart ai.
Smoke test
infra/smoke-models.sh <stack> port-forward svc/ai-gateway và gọi mọi alias bằng key của server: search, listing-read với một ảnh, scam-check, stt với một đoạn audio im lặng, embed-text (1024 chiều), và embed-image với một ảnh và với một đoạn chữ (1152 chiều). Nó bỏ qua các lời gọi embed-image khi EMBED_IMAGE_MODEL của stack rỗng. Sau đó nó kiểm tra server-llm bị từ chối embed-text, server-assist và server-trust bị từ chối search, mỗi lần bằng 403. Nó cần hurl và kubectl.
Đổi mô hình hoặc nhà cung cấp
Bên gọi luôn hỏi cùng các alias. Để đổi thứ trả lời search:
-
Sửa values
Trong
chart/values.yamlcủa repoai, đặtgateway.aliases.search.modellà chuỗi mô hình của LiteLLM, kèm tiền tố nhà cung cấp (openai/anthropic/claude-haiku-5.5), vàgateway.aliases.search.apiBaselà base URL tương thích OpenAI của nó. Để chỉ đổi một stack, đặt chúng dướigateway.aliases.searchtrongvaluesObjectcủaai-<stack>ởinfra/argocd/ai.yaml. Chart từ chối render nếu một trong hai để trống. -
Thêm key của nhà cung cấp
Với nhà cung cấp khác OpenRouter, thêm key của họ vào
infra/stack/secrets/<stack>.envvà vàolitellm-secretstrong lệnh seal, ghi tên nó vàoapiKeySecret, seal lại cả hai stack rồi push, và khởi động lạiai-gateway. -
Chạy test và push
Chạy
helm unittest charttrong repoai, commit rồi push lênmaincủa nó. Argo CD syncai-dev;ai-prodnhận thay đổi cùng bản phát hành tiếp theo. Annotationchecksum/configtrên pod củaai-gatewayđổi theo cấu hình, nên gateway khởi động lại với mô hình mới. -
Kiểm tra một lần tìm kiếm
Tìm một thứ gì đó trên stack và đọc log của server. Dòng
the model did not read the querynghĩa là mô hình mới thất bại.
Server yêu cầu response format json_schema chặt. Mô hình bỏ qua nó sẽ trả văn bản server không giải mã được, và tìm kiếm quay về chữ gốc ở mọi câu truy vấn. Để đổi embed-text hay embed-image, xem Vector và version của chúng: version của vector đổi theo mô hình.
Đổi ngân sách
-
Sửa values của stack
Trong
infra/argocd/ai.yaml, dướivaluesObjectcủaai-devhoặcai-prod, đổidailyUnitshoặctpmLimit,rpmLimitcủa một key dướigateway.keys. Ngân sách theo ngày của agent nằm trongchart/values.yamlcủa repoai. -
Kiểm tra và push
Chạy
infra/check.sh, lệnh này render chartaivới values của từng stack, rồi commit và push repo tổng.rootcập nhật Application,ai-<stack>sync, và Jobai-gateway-keyschạy/key/updatetrên mọi key với giới hạn mới. -
Kiểm tra Job
kubectl -n shopnexus-dev logs job/ai-gateway-keysin một dòngkey <tên>: HTTP 200cho mỗi key.
Thêm một alias mô hình
Một alias là một mục của gateway.aliases, và một key chỉ tới được các alias trong models của nó:
- Thêm mục vào
gateway.aliasestrongchart/values.yamlcủa repoai, vớimodel,apiBase,price(token,secondhoặcusd), vàapiKeySecret,mode,extraBody,inputCostPerTokenvàoutputCostPerTokenkhi cần. - Thêm tên của nó vào
modelscủa key gọi nó. Với một bên gọi mới, thêm một mục vàogateway.keysvớisecret(namevàkeytrong Secret của bên gọi) vàmodels, đặtdailyUnitsvàtpmLimithoặcrpmLimitcho từng stack tronginfra/argocd/ai.yaml, rồi thêm key vào danh sách key lệnh seal sinh ra và vào Secret của bên gọi. - Chạy
helm unittest charttrong repoaivàinfra/check.shtrong repo tổng trước khi push. Chart từ chối một key nêu alias không tồn tại, một key gồm alias tính giá theo đơn vị khác nhau, một key không có giới hạn nào, và một alias không có model.
Alias mới chỉ được dùng bởi bên gọi nào hỏi tới nó.
Admin UI và mức chi
Host dashboard litellm.<domain> của stack, nằm sau phần đăng nhập của console, dẫn tới Service ai-gateway. Từ shell, dùng port-forward và master key:
kubectl -n shopnexus-dev get secret litellm-secrets -o jsonpath='{.data.LITELLM_MASTER_KEY}' | base64 -d; echo
kubectl -n shopnexus-dev port-forward svc/ai-gateway 4000:4000Mở http://localhost:4000/ui và đăng nhập với user admin, mật khẩu là master key. UI liệt kê các key có alias server-llm, server-stt, server-assist, server-trust, server-embed-index, server-embed-search và agent, mỗi key kèm mức chi, ngân sách và thời điểm reset. Với prod, dùng shopnexus-prod.
Để đọc mức chi từ shell trong lúc port-forward đang chạy:
master=$(kubectl -n shopnexus-dev get secret litellm-secrets -o jsonpath='{.data.LITELLM_MASTER_KEY}' | base64 -d)
key=$(kubectl -n shopnexus-dev get secret server-secrets -o jsonpath='{.data.LLM_API_KEY}' | base64 -d)
curl -s "http://localhost:4000/key/info?key=$key" -H "Authorization: Bearer $master"info.spend tính bằng đơn vị ngân sách: mức chi 0.05 trên server-llm là 50.000 token trong ngày, trên agent là 0,05 USD. info.max_budget là giới hạn của ngày, info.budget_reset_at là lần reset kế tiếp.
Quy tắc chính
- Bên gọi chỉ gọi các alias của
gateway.aliases; mô hình đứng sau mỗi alias được đặt trongchart/values.yamlcủa repoai. - Ngân sách được đặt theo stack trong
infra/argocd/ai.yaml, bằng token, giây hoặc phần triệu đô la. - Index và tìm kiếm embed bằng hai key riêng,
server-embed-indexvàserver-embed-search. - Giá trị key đến từ lệnh seal; Job
ai-gateway-keyschỉ ghi chúng vào LiteLLM. - Sau khi seal lại
litellm-secrets,ai-gatewaychỉ khởi động lại bằng tay. embed-textgiữ ghim DeepInfra chừng nàoEMBED_TEXT_VERSIONcòn ghi bge-m3 của TEI.