Repository navigation
Open
Description
Agent
- Tool: Claude Code
- Tool version: 2.1.325
- Model (full id): claude-sonnet-5-5
- Host (CLI / IDE / GitHub coding agent / other): other (T3 Code desktop app, Claude Code harness)
- Date (UTC): 2026-11-14
User request
- Verbatim:
Original request (Hungarian)
Feladat: építs Voyage AI integrációt a `QuantumNous/new-api` projektben. A cél ugyanaz, mint a Sim projektben: szöveges embedding modellek, contextualized embeddings, rerank és, ha a projektben van multimodal embedding, a multimodal modellek is, a projekt saját mintái szerint. Magyarul kommunikálj velem, a kód, a commit és a PR angolul legyen.
Referencia: https://github.com/simstudioai/sim/pull/9942 (a Sim integráció). Nézd meg a diffjét és a leírását mintának, de a kódot ne másold: a `QuantumNous/new-api` saját mintáit kövesd. Ahol ez a prompt Sim-beli megoldást említ (pl. blokk, BYOK, hosted kulcs, workflow-művelet, realtime szerver), az csak akkor vonatkozik rád, ha a projektben van megfelelője.
## 1. Indulás és előkészítés (ebben a sorrendben)
1. Mindig az upstream legfrissebb default branchéből indulj (nem mindenhol `main`), vagy abból az ágból, amit az upstream CONTRIBUTING a PR-oknak előír. Frissítsd az origin forkot is, csak fast-forwarddal: `gh repo sync fzowl/new-api --source QuantumNous/new-api`. Ha az ágak szétváltak, ne erőltesd, kérdezz.
2. Keress meg minden korábbi, nyitott PR-t, amit `fzoll` vagy `fzowl` nyitott az upstreamben és a forkban, és zárd le őket komment nélkül. Zárás előtt olvasd el őket: ami még jó, azt használd fel, de a mostani upstream kódra építs. Más repók PR-jaihoz ne nyúlj.
3. Nézd át a repót, különösen az embedding modell integrációkat (katalógus, providerek, kulcskezelés, blokkok/tool-ok, árazás, tesztek). A legközelebbi meglévő embedding providert tekintsd mintának.
4. Ha a projektben nincs embedding provider réteg vagy más természetes integrációs pont (embedding, rerank, multimodal), ne találj ki újat: írd le, mit néztél meg és miért nincs hova integrálni, és kérdezz, mielőtt bármit építesz.
## 2. Mit kell megépíteni
**Szöveges embedding modellek** a projekt meglévő embedding rétegében, a legközelebbi provider mintája szerint (katalógus, adapter, kulcs/BYOK, hosted kulcs `VOYAGE_API_KEY`, árazás, blokk/tool, generált fájlok, docs).
Modellek (a limitek és árak 2026-11-12 állapotúak, indulás előtt ellenőrizd a Voyage docs-ban és élő hívással):
- voyage-4-large, voyage-4, voyage-4-lite, voyage-code-4: alap 1024 dimenzió, Matryoshka 2048/1024/512/256, 32k kontextus.
- voyage-3-large, voyage-3.5, voyage-3.5-lite, voyage-code-3: ugyanígy.
- voyage-finance-2 (32k), voyage-law-2 (16k): fix 1024 dimenzió.
- Endpoint: `POST /v1/embeddings`; `input_type` csak `document` vagy `query`; `output_dimension` csak ha kérték.
- Kérésenkénti tokenplafon: 1M a *-lite modelleknél, 320K voyage-4/3.5-nél, 120K a többinél; legfeljebb 1000 input. A voyage-code-4-hez nincs dokumentált plafon, ne találj ki számot.
- Árak ($/1M token): voyage-4-large 0.12, voyage-4 0.06, voyage-4-lite 0.02, voyage-code-4 0.12, finance-2 0.12, law-2 0.12, 3-large 0.18, 3.5 0.06, 3.5-lite 0.02, code-3 0.18.
- Ha a projekt knowledge base / vektoros indexelő útvonalához további kapacitás-, beállítás- vagy setup-táblák kellenek, és a Cohere/Mistral-szerű providerek is kimaradnak onnan, ne bővítsd a scope-ot: jelezd follow-upként.
**Reranker.** Nézd meg, van-e reranker a projektben. Vedd fel a Voyage rerankert: `rerank-3` és `rerank-3-lite` (ezek a jelenlegi ajánlott modellek), plusz `rerank-2.5`, `rerank-2.5-lite`. `POST /v1/rerank`, `query`, `documents`, opcionális `top_k`, `return_documents: true`. Árak: rerank-3 0.05, rerank-3-lite 0.02, rerank-2.5 0.05, rerank-2.5-lite 0.02 $/1M token. Teszteléshez is `rerank-3`-at használj, ne a 2.5-öt. Ha a meglévő rerankert nem lehet kis változtatással provider-függetlenné tenni, külön workflow-művelet legyen, és jelezd, hogy a keresési reranker nem változott.
**Contextualized embeddings.** Modellek: `voyage-context-4` és `voyage-context-3`; `POST /v1/contextualizedembeddings`. A végső elvárás: az API hívás mindig `enable_auto_chunking: true` és `chunk_size: 32_000` (a Python kwargs megfelelője: `kwargs["chunk_size"] = 32_000`, `kwargs["enable_auto_chunking"] = True`).
Az API kényszerei, élő hívással ellenőrizve:
- auto-chunking csak `input_type: "document"` mellett működik, query vagy hiányzó input type 400-at ad;
- auto-chunkingnál az input lapos `list[str]`, egy string egy dokumentum; a `list[list[str]]` 400-at ad ("auto-chunking expects one string per document");
- ezért document módban `list[str]` az input, query módban nincs auto-chunk (lapos lista vagy egy lekérdezést tartalmazó belső lista);
- a válasz chunkonként visszaadja a `text`-et, ha az API chunkolt: add vissza `chunks` kimenetként is. A nem auto-chunkolt válaszban nincs `text`.
- Ha a projekt natívan `list[list[str]]` inputot vár, kérdezz rá, mielőtt ezt felülírod. Én eredetileg `list[list[str]]`-t kértem, a végén a document módú auto-chunkingot választottam.
**Multimodal embedding.** Nézd meg, van-e multimodal embedding a projektben (képet, videót vagy vegyes tartalmat embeddelő útvonal, tool, blokk, modellkatalógus). Ha van, vedd fel a Voyage multimodal modelleket is (`voyage-multimodal-3`, `voyage-multimodal-3.5`; indulás előtt ellenőrizd a docs-ban, hogy melyik modell mit kezel). Endpoint: `POST /v1/multimodalembeddings`; az input elemei `{"content": [ ... ]}` alakúak, ahol a tartalomelem lehet `text`, `image_url`, `image_base64` (data URL, png/jpeg/webp/gif), és ha a modell támogatja, videó; egy kérésben egységesen csak URL vagy csak base64 kép szerepelhet. Paraméterek: `input_type` (document/query), `truncation`, kódolás. Ellenőrizd a docs-ból és élő hívással a válasz pontos alakját, a limiteket, a dimenziókat és az árakat, mielőtt a kimenetet típusozod, és ne találj ki mezőt. Ha a projektben van fájlfeltöltés/tárolás, a meglévő mintával oldd meg, hogy a képet/videót fájlból is meg lehessen adni, ne csak URL-ből. Ha a projektben nincs multimodal embedding, ne építsd meg, hanem jelezd a beszámolóban. (A Sim projektben nincs, ott kihagytuk.)
## 3. Kötelező tervezési szabályok
- **Nincs default modell.** A modellt mindig explicit meg kell adni (embedding, contextualized és rerank is): a tool paramétere `required`, a sémában kötelező, a végrehajtás hiányzó modellnél érthető hibát ad. A többi providernél meglévő default marad. Figyelj arra, hogy egy UI dropdown üres `value` mellett is magától az első opciót választja ki. Ezt úgy kerüld el, hogy a modellmező olyan komponens legyen, ami nem választ ki semmit (Sim-ben `combobox` + `emptyIsValid: true`), és a böngészőben ellenőrizd, hogy a mező tényleg üres.
- **Hivatalos SDK-k.** Csak a hivatalos Voyage SDK-kat használd (PyPI `voyageai`, npm `voyageai`), kézzel írt kliens helyett. Ha a projekt meglévő providerei nyers REST adaptereket használnak egy közös retry/admission/quota réteggel, akkor a minta követése és az SDK használata ütközik: ezt kérdezd meg, ne dönts egyedül. Sim-ben REST adaptert választottam, az SDK-t csak az ellenőrzéshez használtuk: ugyanazzal a kéréssel a vektorok és a tokenszám azonosak voltak. Python csak akkor jön szóba, ha a projektben van Python embedding kód. Ha a projekt nyelvéhez (pl. Go, Java, Rust, Lua, C++) nincs hivatalos Voyage SDK, a projekt meglévő providereinek mintájára írj REST adaptert a Voyage API-ra, és ezt a döntést írd bele a beszámolóba; ha a projektben nincs ilyen minta, kérdezz.
- **Token-aware batching.** Ha a projekt sok szöveget embeddel egyszerre (pl. indexelésnél), a Voyage kéréseket a modell kérésenkénti tokenplafonja és az 1000 inputos limit szerint darabold. A tokenszámot az SDK `count_tokens`/`tokenize` függvényével számold, ne becsüld. Ha a projektnek van meglévő batching rétege, abba illeszd be a Voyage limitjeit; ha nincs, a legközelebbi provider mintáját kövesd. A darabolt kérések vektorai az eredeti input sorrendjében jöjjenek vissza.
- **Explicit definíciókat szeretek**: nevesített modellek, kötelező mezők, nincs csendes fallback, hiányzó usage esetén a számlázás hibával áll meg (nem 0 dollár).
- A kulcs (`VOYAGE_API_KEY`) csak a környezetből jöhet. Soha ne írd fájlba, commitba, PR-ba, logba vagy riportba. Élő hívásból keveset és kicsit végezz. Ha a teszt a kulcsot a tesztelt alkalmazásnak adja át, tárold el az alkalmazás env-változói között és hivatkozz rá (pl. `{{VOYAGE_API_KEY}}`), ne írd ki az értékét.
- Voyage hibatörzs: `{"detail": "<szöveg>"}`; vegyél fel a projekt hibakinyerőibe egy, a Voyage-ra explicit szűkített kinyerőt.
## 4. Ellenőrzés: a valódi alkalmazáson keresztül
Ne csak unit teszt vagy saját script legyen. Indítsd el a projektet lokálisan (eldobható adatbázissal, szükség esetén realtime szerverrel, eldobható titkokkal), és futtass mindent a valódi végrehajtón át:
- minden új embedding modell (natív dimenzió, Matryoshka modelleknél query + kisebb dimenzió, 2048, batch);
- mindkét contextualized modell, document és query módban, dimenziókkal, a chunk szöveg visszaadásával;
- mind a négy reranker modell és a `top_k`;
- ha van multimodal: minden multimodal modell szöveggel, képpel (URL és base64) és vegyes tartalommal, query és document módban;
- token-aware batching: egy plafon feletti input több kérésre bomlik, a vektorok száma és sorrendje egyezik az inputéval (élő hívásból ehhez is keveset; a darabolás logikája unit tesztben is legyen);
- negatív esetek: hiányzó modell, más provider modellje, ismeretlen modell, document módban előre darabolt lista, hiányzó input type;
- ha van BYOK vagy felhasználói kulcskezelés: a kulcs mentése és listázása;
- ha van UI, a böngészőben: az új blokk/beállítás megjelenik, a modellmezők üresek és kötelezőek, a választás beíródik, a futtatás eredménye látszik.
Ha a projekt (vagy egy része) ezen a gépen nem futtatható (pl. nincs Docker, kevés a memória/lemez, túl nagy a build), ne kerülgesd: írd le pontosan, mit nem tudtál elindítani és mit nem tudtál ellenőrizni, és kérdezz, mielőtt továbblépsz.
Takarítsd el utána: szerverek, konténerek, titkokat tartalmazó fájlok. Tegyél bele az eredmények összefoglalásába azt is, amit NEM próbáltál ki.
## 5. Folyamat és minőség
- Először hasonlítsd össze a projekt konvencióit (generált fájlok, katalógusok, docs, audit/lint szabályok, tesztelési szabályok) és kövesd őket. Futtasd a projekt teljes helyi gate-jét (lint, type-check, auditok, tesztek, generátorok), a flaky, terhelés alatt időtúllépő teszteket külön futtatva ellenőrizd.
- Teszteket csak hibamódokra írj (rossz input, kötelező mező, API-kényszer, számlázás fail-closed), ne a kódot visszamondó teszteket.
- Külön reviewer modellel nézesd át a változást (több kör, csak valódi hibák javítása), majd javítsd a nitek közül, amit érdemes.
- Upstream PR esetén a factory skill review-PR menete érvényes (review PR a forkban, én APPROVED / CHANGE REQUIRED választ adok a threadben). A cél-ág a default branch (a review PR-nál a fork default branche, az upstream PR-nál az upstreamé), kivéve, ha az upstream CONTRIBUTING mást ír elő (pl. `staging`); akkor az az ág, a forkban is. Ha a cél-ág gyorsan mozog, rebase-elj és regenerálj, ha a generált fájlok ütköznek. A PR leírás és a commit üzenet ne említsen AI-t, ügynököt, eszközt vagy modellt, nincs `Co-Authored-By` sor.
- A PR-t kövesd (CI, review botok, maintainer visszajelzések), de ne mergelj és ne zárd le. A fork-PR-okon gyakori, hogy a CI-hoz és a deploy-hoz maintainer jóváhagyás kell: ezt jelezd, ne próbáld megkerülni.
- A végén egy beszámoló: mit építettél, hol tér el a kéréstől és miért, mit ellenőriztél élesben, mit nem, és a follow-upok (pl. KB-indexelés Voyage-zsal, keresési reranker átállítás, márkás ikon).
- Later constraints or corrections from the user (quote, or none): "Nyisd az Issue-t, szerintem ismered az igényt. AGENTS.md szerint járjunk el!"
Out of scope — refuse
- Matched: no
- If yes, what was told to the user (stop here; do not file): not applicable
File gate — do not file unless all are satisfied
- Out of scope (including pass-through): no
- Usage / configuration / integration (answered instead of filing): no
- Required facts present without invention (actual behavior, impact, frequency, evidence in new-api, applicable type fields): yes
- Body is short and factual; no unfiltered AI-generated text: yes
- File: yes
- If no, what was told to the user (stop here): not applicable
Kind
- Bug
- Feature
- Investigation
- Other:
Usage / configuration / integration check
- https://docs.newapi.ai/ — searched the landing page for Voyage, embeddings and rerank: no Voyage channel or guidance.
- https://deepwiki.com/QuantumNous/new-api — page returned HTTP 429, not read.
- README / repo docs:
grep -i voyageover README*.md and docs/ finds nothing. - Relevant code paths and conclusion: there is no Voyage channel type.
relay/channel/jinaandrelay/channel/cohereare the closest embedding/rerank channels (see Research). - Can the current version already do this? (required for feature requests): Partly. Text embeddings work through an OpenAI-type channel with a parameter override
{"input_type": "query", "encoding_format": null}(workaround from closed issue 将voyageai加入渠道 #2680). Rerank, contextualized embeddings and multimodal embeddings do not work this way, and there is no model list or built-in pricing. - Verdict: new feature
Environment
- new-api version / commit / image tag (not
latest/unknown): main at e00ec88 - Deploy source (repo release / official image / main source / other): main source
- Database (sqlite / mysql / postgres): sqlite
Problem facts
- Actual behavior: No Voyage AI channel type. Voyage models can only be reached through an OpenAI-type channel with overrides, and only for text embeddings.
- Impact: Operators who use Voyage embedding, rerank, contextualized or multimodal models cannot route, price or bill them in new-api.
- Frequency: not applicable (missing feature)
- Evidence that the problem is in new-api rather than the client or upstream: Voyage's API differs from the OpenAI-compatible shapes new-api forwards (see Experiments).
Type-specific details
Relay / API
- Request endpoint and method:
POST /v1/embeddings,POST /v1/rerank(Voyage upstream:/v1/embeddings,/v1/rerank,/v1/contextualizedembeddings,/v1/multimodalembeddings) - Channel type: none exists
- Model: voyage-4-large, voyage-4, voyage-4-lite, voyage-code-4, voyage-3-large, voyage-3.5, voyage-3.5-lite, voyage-code-3, voyage-finance-2, voyage-law-2, voyage-context-4, voyage-context-3, voyage-multimodal-3, voyage-multimodal-3.5, rerank-3, rerank-3-lite, rerank-2.5, rerank-2.5-lite
- Conversion format: OpenAI embeddings and Jina-style rerank to Voyage-native bodies
- Pass-through enabled: no
- Evidence of upstream native support: https://docs.voyageai.com/reference/embeddings-api , https://docs.voyageai.com/reference/reranker-api , https://docs.voyageai.com/reference/contextualized-embeddings-api , https://docs.voyageai.com/reference/multimodal-embeddings-api
- Equivalent redacted request sent directly upstream: see Experiments
- Same request through new-api: see Experiments
Billing
- Request endpoint and model: all models above
- Response
usage: Voyage returns only{"total_tokens": n}; multimodal returns{"text_tokens", "image_pixels", "video_pixels", "total_tokens"} - Relevant ratio or pricing configuration: none today
- Consumption log: not applicable
- Expected charge and calculation basis: https://docs.voyageai.com/docs/pricing , text tokens per 1M tokens; multimodal also $0.60 per billion pixels
Frontend
- Page path: Channels, create channel type list
- Browser and version: not applicable
- Active theme: not applicable
- Relevant browser Console / Network errors: not applicable
Deployment / upgrade
not applicable
Reproduction and expected result
- Steps to reproduce: create a Jina-type channel with base URL
https://api.voyageai.comand sendPOST /v1/rerankwithmodel: rerank-3,top_n. - Expected result: ranked results are returned and billed from Voyage's reported tokens.
- Related screenshots (optional): none
Feature (feature requests only)
- Feature description: A built-in Voyage AI channel for text embeddings, contextualized embeddings, multimodal embeddings and rerank, with an explicit model list, built-in prices and fail-closed billing when Voyage reports no usage.
- Use case: Route and bill Voyage models like other providers.
Duplicate check
- Search queries (issues, PRs, discussions):
voyage,voyageai,voyage embedding,voyage rerankin issues and PRs of QuantumNous/new-api. - Closest existing threads: 将voyageai加入渠道 #2680 (closed, "将voyageai加入渠道", answered with the OpenAI-channel override workaround).
- Why this is not a duplicate: 将voyageai加入渠道 #2680 was closed with a workaround for text embeddings only. It added no channel, and rerank, contextualized and multimodal models are not covered.
Research
Docs
- https://docs.newapi.ai/ : no Voyage mention.
- https://deepwiki.com/QuantumNous/new-api : not read (HTTP 429).
- README / other repo docs: no Voyage mention.
- Conclusions: no existing documentation or support for Voyage.
Code
relay/channel/jina/adaptor.go— embeddings and rerank adaptor; its rerank handler (relay/common_handler/rerank.go) readsresults[]and the request carriestop_n.relay/channel/ali/embedding.go— multimodal embedding routed by model name.setting/billing_setting/builtin_billing.go— built-in per-model price expressions.relaykit/dto/error.go—GeneralErrorResponse.Detailalready reads Voyage's{"detail": ...}errors.
Experiments
- Command or redacted request:
POST https://api.voyageai.com/v1/rerankwith{"model":"rerank-3","query":"capital of France","documents":["Berlin","Paris"],"top_n":1};POST https://api.voyageai.com/v1/embeddingswith"encoding_format":"float". - Direct upstream result: both return HTTP 400:
Argument 'top_n' is not supported by our API, andValue 'float' supplied for argument 'encoding_format' is not valid -- accepted values are 'base64'. Rerank takestop_kand answers withdata[], notresults[]. - Result through new-api: not run against the current main without the channel; the Jina rerank handler reads
results[], so a Voyagedata[]response would produce empty results. - Conclusion: the OpenAI and Jina request/response shapes do not fit Voyage; a dedicated channel is needed.
Working theory
- What is broken or missing: no Voyage channel, so no request conversion, model list, price or usage handling for Voyage.
- Why: no channel type or adaptor exists for it.
- What would falsify this: an existing channel type that already serves all four Voyage endpoints with correct billing.
Scope
- In scope for a later PR: one native channel type with a REST adaptor for the four Voyage endpoints, built-in price expressions, model list, frontend channel type entry and locale strings.
- Out of scope / not this repo: knowledge-base or indexing features, a branded channel icon, changes to other channels.
- Large or directional feature? If yes, this issue is for maintainer alignment; do not open a PR yet. No: it follows the existing Jina/Cohere channel pattern. The branch is ready at https://github.com/fzowl/new-api/tree/feat/voyage-ai-channel
Proposed direction
- A channel type "Voyage AI" with an explicit model list; a request naming no known Voyage model is rejected.
- Contextualized embeddings always send
enable_auto_chunking: trueandchunk_size: 32000in document mode. - Billing stops with an error when Voyage reports no usage.
Not verified
- MySQL and PostgreSQL (the change has no schema change).
- Voyage models outside the list above.
Related
Metadata
Metadata
Assignees
Labels
No labels
Activity