cohere

README

---
title: "Cohere"
lang: "en-US"
draft: false
description: "Learn about how to set up a VDP Cohere component https://github.com/instill-ai/instill-core"
---

The Cohere component is an AI component that allows users to connect the AI models served on the Cohere Platform.
It can carry out the following tasks:

- [Text Generation Chat](#text-generation-chat)
- [Text Embeddings](#text-embeddings)
- [Text Reranking](#text-reranking)



## Release Stage

`Alpha`



## Configuration

The component configuration is defined and maintained [here](https://github.com/instill-ai/component/blob/main/ai/cohere/v0/config/definition.json).




## Setup




In order to communicate with Cohere, the following connection details need to be
provided. You may specify them directly in a pipeline recipe as key-value pairs
withing the component's `setup` block, or you can create a **Connection** from
the [**Integration Settings**](https://www.instill.tech/docs/vdp/integration)
page and reference the whole `setup` as `setup:
${connection.<my-connection-id>}`.

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| API Key | `api-key` | string | Fill in your Cohere API key. To find your keys, visit the Cohere dashboard page. |




## Supported Tasks

### Text Generation Chat

Provide text outputs in response to text inputs.


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_TEXT_GENERATION_CHAT` |
| Model Name (required) | `model-name` | string | The Cohere command model to be used |
| Prompt (required) | `prompt` | string | The prompt text |
| System message | `system-message` | string | The system message helps set the behavior of the assistant. For example, you can modify the personality of the assistant or provide specific instructions about how it should behave throughout the conversation. By default, the model’s behavior is using a generic message as "You are a helpful assistant." |
| Documents | `documents` | array[string] | The documents to be used for the model, for optimal performance, the length of each document should be less than 300 words. |
| Prompt Images | `prompt-images` | array[string] | The prompt images (Note: As for 2024-06-24 Cohere models are not multimodal, so images will be ignored.) |
| Chat history | `chat-history` | array[object] | Incorporate external chat history, specifically previous messages within the conversation. Each message should adhere to the format: : \{"role": "The message role, i.e. 'USER' or 'CHATBOT'", "content": "message content"\}. |
| Seed | `seed` | integer | The seed (default=42) |
| Temperature | `temperature` | number | The temperature for sampling (default=0.7) |
| Top K | `top-k` | integer | Top k for sampling (default=10) |
| Max new tokens | `max-new-tokens` | integer | The maximum number of tokens for model to generate (default=50) |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Text | `text` | string | Model Output |
| Citations (optional) | `citations` | array[object] | Citations |
| Usage (optional) | `usage` | object | Token Usage on the Cohere Platform Command Models |






### Text Embeddings

Turn text into a vector of numbers that capture its meaning, unlocking use cases like semantic search.


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_TEXT_EMBEDDINGS` |
| Embedding Type (required) | `embedding-type` | string | Specifies the return type of embedding, Note that 'binary'/'ubinary' options means the component will return packed unsigned binary embeddings. The length of each binary embedding is 1/8 the length of the float embeddings of the provided model. |
| Input Type (required) | `input-type` | string | Specifies the type of input passed to the model |
| Model Name (required) | `model-name` | string | The Cohere embed model to be used |
| Text (required) | `text` | string | The text |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Embedding | `embedding` | array[number] | Embedding of the input text |
| Usage (optional) | `usage` | object | Token usage on the Cohere platform embed models |






### Text Reranking

Sort text inputs by semantic relevance to a specified query.


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_TEXT_RERANKING` |
| Model Name (required) | `model-name` | string | The Cohere rerank model to be used |
| Query (required) | `query` | string | The query |
| Documents (required) | `documents` | array[string] | The documents to be used for reranking |
| Top N | `top-n` | integer | The number of most relevant documents or indices to return. Defaults to the length of the documents (default=3) |
| Maximum number of chunks per document | `max-chunks-per-doc` | integer | The maximum number of chunks to produce internally from a document (default=10) |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Reranked documents | `ranking` | array[string] | Reranked documents |
| Reranked documents relevance (optional) | `relevance` | array[number] | The relevance scores of the reranked documents |
| Usage (optional) | `usage` | object | Search Usage on the Cohere Platform Rerank Models |

Documentation

Index

• Constants
• func Init(bc base.Component) *component
• func IsEmbeddingOutputInt(embeddingType string) bool
• type ChatMessage
• type CohereClient
• type EmbeddingFloatOutput
• type EmbeddingInput
• type EmbeddingIntOutput
• type MultiModalContent
• type RerankInput
• type RerankOutput
• type TextGenerationInput
• type TextGenerationOutput
• type URL

Constants

const (
	TextGenerationTask = "TASK_TEXT_GENERATION_CHAT"
	TextEmbeddingTask  = "TASK_TEXT_EMBEDDINGS"
	TextRerankTask     = "TASK_TEXT_RERANKING"
)

Functions

func Init

func Init(bc base.Component) *component

func IsEmbeddingOutputInt

func IsEmbeddingOutputInt(embeddingType string) bool

Types

type ChatMessage

type ChatMessage struct {
	Role    string              `json:"role"`
	Content []MultiModalContent `json:"content"`
}

type CohereClient

type CohereClient interface {
	// contains filtered or unexported methods
}

type EmbeddingFloatOutput

type EmbeddingFloatOutput struct {
	Usage     embedUsage `json:"usage"`
	Embedding []float64  `json:"embedding"`
}

type EmbeddingInput

type EmbeddingInput struct {
	Text          string `json:"text"`
	ModelName     string `json:"model-name"`
	InputType     string `json:"input-type"`
	EmbeddingType string `json:"embedding-type"`
}

type EmbeddingIntOutput

type EmbeddingIntOutput struct {
	Usage     embedUsage `json:"usage"`
	Embedding []int      `json:"embedding"`
}

type MultiModalContent

type MultiModalContent struct {
	ImageURL URL    `json:"image-url"`
	Text     string `json:"text"`
	Type     string `json:"type"`
}

type RerankInput

type RerankInput struct {
	Query     string   `json:"query"`
	Documents []string `json:"documents"`
	ModelName string   `json:"model-name"`
}

type RerankOutput

type RerankOutput struct {
	Ranking   []string    `json:"ranking"`
	Usage     rerankUsage `json:"usage"`
	Relevance []float64   `json:"relevance"`
}

type TextGenerationInput

type TextGenerationInput struct {
	ChatHistory  []ChatMessage `json:"chat-history"`
	MaxNewTokens int           `json:"max-new-tokens"`
	ModelName    string        `json:"model-name"`
	Prompt       string        `json:"prompt"`
	PromptImages []string      `json:"prompt-images"`
	Seed         int           `json:"seed"`
	SystemMsg    string        `json:"system-message"`
	Temperature  float64       `json:"temperature"`
	TopK         int           `json:"top-k"`
	Documents    []string      `json:"documents"`
}

type TextGenerationOutput

type TextGenerationOutput struct {
	Text      string       `json:"text"`
	Citations []citation   `json:"citations"`
	Usage     commandUsage `json:"usage"`
}

type URL

type URL struct {
	URL string `json:"url"`
}