Skip to main content

Cohere

还没翻译译自英文（tanstack.com）本页 42 段都还没译

The Cohere adapter covers the two retrieval steps of a RAG pipeline:

  • Embeddings (cohereEmbedding): turn text, images, and fused text+image inputs into vectors with embed().
  • Reranking (cohereRerank): reorder candidate documents by relevance to a query with rerank().

It does not support chat(), summarize(), or media generation. Use OpenAI, Anthropic, or Gemini for those. The adapter talks to Cohere's HTTP API directly over fetch, with no SDK dependency.

Installation

Embeddings

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: ["a red guitar", "a blue drum kit"],
  modelOptions: { inputType: "search_document" },
});

console.log(result.embeddings[0]?.vector);
console.log(result.usage?.promptTokens);

inputType is required by Cohere's API. Use search_document at index time and search_query at query time (or classification / clustering for those workloads). TanStack AI enforces this at the type level, so modelOptions is required for Cohere embedding calls.

Multimodal Embeddings

embed-v4.0 embeds images alongside text. An image part produces an image vector. A nested array of parts ([textPart, imagePart]) fuses text and image into one vector, which suits product catalogs and screenshot search. The outer array is the item list, so nest to fuse:

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const productPhoto = "iVBORw0KGgo..."; // base64 image data

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: [
    {
      type: "image",
      source: {
        type: "data",
        value: productPhoto,
        mimeType: "image/png",
      },
    },
    // A nested array fuses its parts into a single vector.
    [
      { type: "text", content: "Fender Stratocaster, sunburst finish" },
      {
        type: "image",
        source: {
          type: "data",
          value: productPhoto,
          mimeType: "image/png",
        },
      },
    ],
  ],
  modelOptions: { inputType: "search_document" },
});

console.log(result.embeddings.length); // 2

Cohere's API does not fetch remote image URLs. Pass base64 data (or a data: URI), or opt into adapter-side downloading:

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const adapter = cohereEmbedding("embed-v4.0", { allowUrlFetch: true });

const result = await embed({
  adapter,
  input: {
    type: "image",
    source: { type: "url", value: "https://example.com/guitar.png" },
  },
  modelOptions: { inputType: "search_document" },
});

Requesting Dimensions

embed-v4.0 supports Matryoshka output dimensions via the top-level dimensions option:

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: "a red guitar",
  dimensions: 1024, // 256 | 512 | 1024 | 1536
  modelOptions: { inputType: "search_document" },
});

Reranking

import { rerank } from "@tanstack/ai";
import { cohereRerank } from "@tanstack/ai-cohere";

const { rerankedDocuments } = await rerank({
  adapter: cohereRerank("rerank-v3.5"),
  query: "talk about rain",
  documents: ["sunny day at the beach", "rainy afternoon in the city"],
});

console.log(rerankedDocuments[0]); // 'rainy afternoon in the city'

For the full reranking guide, with object documents, RAG pipelines, options, and the result shape, see Reranking.

Per-request rerank options go on modelOptions:

import { rerank } from "@tanstack/ai";
import { cohereRerank } from "@tanstack/ai-cohere";

const { ranking } = await rerank({
  adapter: cohereRerank("rerank-v3.5"),
  query: "refund policy",
  documents: ["Returns accepted within 30 days.", "Free shipping over $50."],
  modelOptions: {
    maxTokensPerDoc: 512, // Cap tokens kept per document (Cohere default: 4096)
  },
});

console.log(ranking);

Models

ModelCapabilityDescription
embed-v4.0EmbeddingsMultimodal (text + images), Matryoshka dimensions support
rerank-v3.5RerankingLatest multilingual reranker (recommended)
rerank-english-v3.0RerankingEnglish-optimized reranker
rerank-multilingual-v3.0RerankingMultilingual reranker

Environment Variables

Both adapters read your API key from the environment:

COHERE_API_KEY=your-cohere-api-key
VariableRequiredDescription
COHERE_API_KEYYesYour Cohere API key

Get a key from the Cohere dashboard.

Explicit API Keys

To pass a key directly instead of reading the environment, use the create* factories:

import {
  createCohereEmbedding,
  createCohereRerank,
} from "@tanstack/ai-cohere";

const embedAdapter = createCohereEmbedding(
  "embed-v4.0",
  process.env.MY_COHERE_KEY!,
);
const rerankAdapter = createCohereRerank("rerank-v3.5", "your-cohere-api-key");

Behind a proxy

Route every request through a gateway, such as Cloudflare AI Gateway or a corporate proxy, with baseURL and defaultHeaders. These two option names are the same on every TanStack AI adapter, so one gateway config works for all of them.

import { createCohereEmbedding } from "@tanstack/ai-cohere";

const adapter = createCohereEmbedding("embed-v4.0", process.env.COHERE_API_KEY!, {
  baseURL: "https://gateway.example.com/cohere",
  defaultHeaders: { "cf-aig-authorization": `Bearer ${process.env.GATEWAY_TOKEN}` },
});

baseUrl and headers are aliases of the same two options. If you set both forms, baseURL and defaultHeaders win.

API Reference

cohereEmbedding(model, config?)

Creates an embedding adapter using COHERE_API_KEY from the environment.

  • model: "embed-v4.0"
  • config.baseURL: override the API base URL (default https://api.cohere.com). baseUrl is an alias.
  • config.defaultHeaders: extra request headers. headers is an alias.
  • config.allowUrlFetch: download http(s) image URLs and inline them as base64 (default false)

createCohereEmbedding(model, apiKey, config?)

Same as cohereEmbedding with an explicit API key.

cohereRerank(model, config?)

Creates a rerank adapter using COHERE_API_KEY from the environment.

  • model: one of the rerank models above
  • config.baseURL: override the API base URL (default https://api.cohere.com). baseUrl is an alias.
  • config.defaultHeaders: extra request headers. headers is an alias.

createCohereRerank(model, apiKey, config?)

Same as cohereRerank with an explicit API key.

Next Steps

Edit on GitHub
AI 翻译查看英文原文