Skip to content

feat: Voyage AI channel (embeddings, contextualized and multimodal embeddings, rerank) #8331

Open

Description

@fzowl

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 voyage over README*.md and docs/ finds nothing.
  • Relevant code paths and conclusion: there is no Voyage channel type. relay/channel/jina and relay/channel/cohere are 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

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.com and send POST /v1/rerank with model: 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 rerank in 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

Code

  • relay/channel/jina/adaptor.go — embeddings and rerank adaptor; its rerank handler (relay/common_handler/rerank.go) reads results[] and the request carries top_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.Detail already reads Voyage's {"detail": ...} errors.

Experiments

  • Command or redacted request: POST https://api.voyageai.com/v1/rerank with {"model":"rerank-3","query":"capital of France","documents":["Berlin","Paris"],"top_n":1}; POST https://api.voyageai.com/v1/embeddings with "encoding_format":"float".
  • Direct upstream result: both return HTTP 400: Argument 'top_n' is not supported by our API, and Value 'float' supplied for argument 'encoding_format' is not valid -- accepted values are 'base64'. Rerank takes top_k and answers with data[], not results[].
  • Result through new-api: not run against the current main without the channel; the Jina rerank handler reads results[], so a Voyage data[] 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: true and chunk_size: 32000 in 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions