Bỏ qua đến nội dung
ShopNexus Docs
Trên trang này Triển khai 1/20

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.

AliasUpstreamMô hìnhDùng cho
searchOpenRouteranthropic/claude-haiku-5.5đọc câu truy vấn tìm kiếm
listing-readOpenRouteranthropic/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-checkOpenRouteranthropic/claude-haiku-5.5kiểm tra một khung chat xem có lừa đảo không
console-agentOpenRouteranthropic/claude-sonnet-5.5console agent
embed-textOpenRouter, chỉ DeepInfrabaai/bge-m3, 1024 chiềuvector chữ của tin đăng và câu truy vấn
embed-imageai-modelssiglip2-so400m-patch16-384, 1152 chiềuvector ảnh, và các đoạn chữ tiếng Anh ngắn cho text tower của SigLIP
sttai-modelsgipformer-1.5chuyể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")]
Những gì ai-dev render vào shopnexus-dev
ValuesNằm ởChứa
lựa chọn của hubchart/values.yaml trong repo aicá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 stackvaluesObject của ai-<stack> trong infra/argocd/ai.yamlstack, 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"]
Một câu truy vấn tìm kiếm, từ server tới mô hình
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"]
Một lượt đọc video, từ server tới ai-models và mô hình
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"]
Embedding, từ server tới OpenRouter và ai-models

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-fp32

Console 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:

chart/values.yaml trong repo ai
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: true

Tiề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 usage củ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-m3 từ 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-text ghim DeepInfra với allow_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-text mấ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ì:

priceGiá1 đơn vị ngân sách là
token0.000001 mỗi token, cả input lẫn output1.000.000 token
second0.000001 mỗi giây audio1.000.000 giây
usdgiá niêm yết của mô hình, inputCostPerToken và outputCostPerToken1 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.

KeySecretAliasdailyUnits devgiới hạn devdailyUnits prodgiới hạn prod
server-llmserver-secrets LLM_API_KEYsearch200.000 token20.000 tpm2.000.000 token100.000 tpm
server-sttserver-secrets STT_API_KEYstt3.600 giây10 rpm36.000 giây60 rpm
server-assistserver-secrets ASSIST_LLM_API_KEYlisting-read1.200.000 token60.000 tpm12.000.000 token300.000 tpm
server-trustserver-secrets TRUST_LLM_API_KEYscam-check600.000 token30.000 tpm6.000.000 token150.000 tpm
server-embed-indexserver-secrets EMBED_INDEX_API_KEYembed-text, embed-image10.000.000 token120 rpm50.000.000 token600 rpm
server-embed-searchserver-secrets EMBED_SEARCH_API_KEYembed-text, embed-image1.000.000 token60 rpm10.000.000 token600 rpm
agentagent-secrets AGENT_LLM_API_KEYconsole-agent20 USD100.000 tpm20 USD200.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"]
ai-gateway-keys ở mỗi lần sync, cho từng key

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-keys

argocd.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.yaml trong infra/stack khai báo một managed role litellm lấy mật khẩu từ Secret litellm-db, và một Database của CNPG tên litellm do role đó sở hữu (wave 1 của stack).
  • ai-gateway ghép DATABASE_URL=postgresql://litellm:$(DB_PASSWORD)@postgres-rw:5432/litellm từ 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>.envSeal vàoAi đọc
LITELLM_MASTER_KEYlitellm-secretsai-gateway, Job ai-gateway-keys, bạn trong admin UI
OPENROUTER_API_KEYlitellm-secretsai-gateway, khi gọi OpenRouter
LITELLM_DB_PASSWORDlitellm-db (basic-auth), khóa passwordCNPG 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_KEYserver-secretsserver; Job ai-gateway-keys
AGENT_LLM_API_KEYagent-secretsconsole 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-gateway

Mộ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
Tìm kiếm khi ai-gateway từ chối

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-models

Khung 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.

Stackmodels.embedModelsBộ nhớ xin, giới hạnSố đo
devrỗng2Gi, 3Gichỉ giọng nói và khung hình đạt đỉnh 2,42 GiB ngày 2026-11-10
prodsiglip2-so400m-patch16-384=/models/siglip2-so400m-patch16-3846Gi, 8Gi4,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:

  1. Sửa values

    Trong chart/values.yaml của repo ai, đặt gateway.aliases.search.model là 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.apiBase là base URL tương thích OpenAI của nó. Để chỉ đổi một stack, đặt chúng dưới gateway.aliases.search trong valuesObject của ai-<stack> ở infra/argocd/ai.yaml. Chart từ chối render nếu một trong hai để trống.

  2. 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>.env và vào litellm-secrets trong lệnh seal, ghi tên nó vào apiKeySecret, seal lại cả hai stack rồi push, và khởi động lại ai-gateway.

  3. Chạy test và push

    Chạy helm unittest chart trong repo ai, commit rồi push lên main của nó. Argo CD sync ai-dev; ai-prod nhận thay đổi cùng bản phát hành tiếp theo. Annotation checksum/config trên pod của ai-gateway đổi theo cấu hình, nên gateway khởi động lại với mô hình mới.

  4. 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 query nghĩ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

  1. Sửa values của stack

    Trong infra/argocd/ai.yaml, dưới valuesObject của ai-dev hoặc ai-prod, đổi dailyUnits hoặc tpmLimit, rpmLimit của một key dưới gateway.keys. Ngân sách theo ngày của agent nằm trong chart/values.yaml của repo ai.

  2. Kiểm tra và push

    Chạy infra/check.sh, lệnh này render chart ai với values của từng stack, rồi commit và push repo tổng. root cập nhật Application, ai-<stack> sync, và Job ai-gateway-keys chạy /key/update trên mọi key với giới hạn mới.

  3. Kiểm tra Job

    kubectl -n shopnexus-dev logs job/ai-gateway-keys in một dòng key <tên>: HTTP 200 cho 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ó:

  1. Thêm mục vào gateway.aliases trong chart/values.yaml của repo ai, với model, apiBase, price (token, second hoặc usd), và apiKeySecret, mode, extraBody, inputCostPerToken và outputCostPerToken khi cần.
  2. Thêm tên của nó vào models của key gọi nó. Với một bên gọi mới, thêm một mục vào gateway.keys với secret (name và key trong Secret của bên gọi) và models, đặt dailyUnits và tpmLimit hoặc rpmLimit cho từng stack trong infra/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.
  3. Chạy helm unittest chart trong repo ai và infra/check.sh trong 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:4000

Mở 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 trong chart/values.yaml của repo ai.
  • 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-index và server-embed-search.
  • Giá trị key đến từ lệnh seal; Job ai-gateway-keys chỉ ghi chúng vào LiteLLM.
  • Sau khi seal lại litellm-secrets, ai-gateway chỉ khởi động lại bằng tay.
  • embed-text giữ ghim DeepInfra chừng nào EMBED_TEXT_VERSION còn ghi bge-m3 của TEI.
ShopNexus Docs
EN VI