genai

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2024 License: Apache-2.0, Apache-2.0 Imports: 14 Imported by: 89

Documentation

Overview

Package genai is a client for the Google AI generative models.

NOTE: This client uses the v1beta version of the API.

Getting started

Reading the examples is the best way to learn how to use this package.

Authorization

You will need an API key to use the service. See the setup tutorial for details.

Errors

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Ptr added in v0.5.0 

func Ptr[T any](t T) *T

Ptr returns a pointer to its argument. It can be used to initialize pointer fields: 

model.Temperature = genai.Ptr[float32](0.1)

Types

type BatchEmbedContentsResponse added in v0.6.0 

type BatchEmbedContentsResponse struct {
	// Output only. The embeddings for each request, in the same order as provided
	// in the batch request.
	Embeddings []*ContentEmbedding
}

BatchEmbedContentsResponse is the response to a `BatchEmbedContentsRequest`.

type Blob 

type Blob struct {
	// The IANA standard MIME type of the source data.
	// Accepted types include: "image/png", "image/jpeg", "image/heic",
	// "image/heif", "image/webp".
	MIMEType string
	// Raw bytes for media formats.
	Data []byte
}

Blob contains raw media bytes.

func ImageData 

func ImageData(format string, data []byte) Blob

ImageData is a convenience function for creating an image Blob for input to a model. The format should be the second part of the MIME type, after "image/". For example, for a PNG image, pass "png".

type BlockReason 

type BlockReason int32

BlockReason is specifies what was the reason why prompt was blocked. 

const (
	// BlockReasonUnspecified means default value. This value is unused.
	BlockReasonUnspecified BlockReason = 0
	// BlockReasonSafety means prompt was blocked due to safety reasons. You can inspect
	// `safety_ratings` to understand which safety category blocked it.
	BlockReasonSafety BlockReason = 1
	// BlockReasonOther means prompt was blocked due to unknown reaasons.
	BlockReasonOther BlockReason = 2
)

func (BlockReason) String 

func (v BlockReason) String() string

type BlockedError 

type BlockedError struct {
	// If non-nil, the model's response was blocked.
	// Consult the FinishReason field for details.
	Candidate *Candidate

	// If non-nil, there was a problem with the prompt.
	PromptFeedback *PromptFeedback
}

A BlockedError indicates that the model's response was blocked. There can be two underlying causes: the prompt or a candidate response.

func (*BlockedError) Error 

func (e *BlockedError) Error() string

type Candidate 

type Candidate struct {
	// Output only. Index of the candidate in the list of candidates.
	Index int32
	// Output only. Generated content returned from the model.
	Content *Content
	// Optional. Output only. The reason why the model stopped generating tokens.
	//
	// If empty, the model has not stopped generating the tokens.
	FinishReason FinishReason
	// List of ratings for the safety of a response candidate.
	//
	// There is at most one rating per category.
	SafetyRatings []*SafetyRating
	// Output only. Citation information for model-generated candidate.
	//
	// This field may be populated with recitation information for any text
	// included in the `content`. These are passages that are "recited" from
	// copyrighted material in the foundational LLM's training data.
	CitationMetadata *CitationMetadata
	// Output only. Token count for this candidate.
	TokenCount int32
}

Candidate is a response candidate generated from the model.

func (*Candidate) FunctionCalls added in v0.11.0 

func (c *Candidate) FunctionCalls() []FunctionCall

FunctionCalls return all the FunctionCall parts in the candidate.

type ChatSession 

type ChatSession struct {
	History []*Content
	// contains filtered or unexported fields
}

A ChatSession provides interactive chat.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	model := client.GenerativeModel("gemini-1.0-pro")
	cs := model.StartChat()

	send := func(msg string) *genai.GenerateContentResponse {
		fmt.Printf("== Me: %s\n== Model:\n", msg)
		res, err := cs.SendMessage(ctx, genai.Text(msg))
		if err != nil {
			log.Fatal(err)
		}
		return res
	}

	res := send("Can you name some brands of air fryer?")
	printResponse(res)
	iter := cs.SendMessageStream(ctx, genai.Text("Which one of those do you recommend?"))
	for {
		res, err := iter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		printResponse(res)
	}

	for i, c := range cs.History {
		log.Printf("    %d: %+v", i, c)
	}
	res = send("Why do you like the Philips?")
	if err != nil {
		log.Fatal(err)
	}
	printResponse(res)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:
Example (History)

This example shows how to set the History field on ChatSession explicitly. 

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	model := client.GenerativeModel("gemini-1.0-pro")
	cs := model.StartChat()

	cs.History = []*genai.Content{
		&genai.Content{
			Parts: []genai.Part{
				genai.Text("Hello, I have 2 dogs in my house."),
			},
			Role: "user",
		},
		&genai.Content{
			Parts: []genai.Part{
				genai.Text("Great to meet you. What would you like to know?"),
			},
			Role: "model",
		},
	}

	res, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
	if err != nil {
		log.Fatal(err)
	}
	printResponse(res)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:

func (*ChatSession) SendMessage 

func (cs *ChatSession) SendMessage(ctx context.Context, parts ...Part) (*GenerateContentResponse, error)

SendMessage sends a request to the model as part of a chat session.

func (*ChatSession) SendMessageStream 

func (cs *ChatSession) SendMessageStream(ctx context.Context, parts ...Part) *GenerateContentResponseIterator

SendMessageStream is like SendMessage, but with a streaming request.

type CitationMetadata 

type CitationMetadata struct {
	// Citations to sources for a specific response.
	CitationSources []*CitationSource
}

CitationMetadata is a collection of source attributions for a piece of content.

type CitationSource 

type CitationSource struct {
	// Optional. Start of segment of the response that is attributed to this
	// source.
	//
	// Index indicates the start of the segment, measured in bytes.
	StartIndex *int32
	// Optional. End of the attributed segment, exclusive.
	EndIndex *int32
	// Optional. URI that is attributed as a source for a portion of the text.
	URI *string
	// Optional. License for the GitHub project that is attributed as a source for
	// segment.
	//
	// License info is required for code citations.
	License string
}

CitationSource contains a citation to a source for a portion of a specific response.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

A Client is a Google generative AI client.

func NewClient 

func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)

NewClient creates a new Google generative AI client.

Clients should be reused instead of created as needed. The methods of Client are safe for concurrent use by multiple goroutines.

You may configure the client by passing in options from the google.golang.org/api/option package.

func (*Client) Close 

func (c *Client) Close() error

Close closes the client.

func (*Client) DeleteFile added in v0.11.0 

func (c *Client) DeleteFile(ctx context.Context, name string) error

DeleteFile deletes the file with the given name. It is an error to delete a file that does not exist.

func (*Client) EmbeddingModel added in v0.2.0 

func (c *Client) EmbeddingModel(name string) *EmbeddingModel

EmbeddingModel creates a new instance of the named embedding model. Example name: "embedding-001" or "models/embedding-001".

func (*Client) GenerativeModel 

func (c *Client) GenerativeModel(name string) *GenerativeModel

GenerativeModel creates a new instance of the named generative model. For instance, "gemini-1.0-pro" or "models/gemini-1.0-pro".

To access a tuned model named NAME, pass "tunedModels/NAME".

func (*Client) GetFile added in v0.11.0 

func (c *Client) GetFile(ctx context.Context, name string) (*File, error)

GetFile returns the named file.

func (*Client) ListFiles added in v0.11.0 

func (c *Client) ListFiles(ctx context.Context) *FileIterator

ListFiles returns an iterator over the uploaded files.

func (*Client) ListModels added in v0.2.0 

func (c *Client) ListModels(ctx context.Context) *ModelInfoIterator
Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	iter := client.ListModels(ctx)
	for {
		m, err := iter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			panic(err)
		}
		fmt.Println(m.Name, m.Description)
	}
}

Output:

func (*Client) UploadFile added in v0.11.0 

func (c *Client) UploadFile(ctx context.Context, name string, r io.Reader, opts *UploadFileOptions) (*File, error)

UploadFile copies the contents of the given io.Reader to file storage associated with the service, and returns information about the resulting file.

The name may be empty, in which case a unique name will be generated. Otherwise, it can contain up to 40 characters that are lowercase alphanumeric or dashes (-), not starting or ending with a dash. The string "files/" is prepended to the name if it does not contain a '/'.

Use the returned file's URI field with a FileData Part to use it for generation.

It is an error to upload a file that already exists.

Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// Use Client.UploadFile to Upload a file to the service.
	// Pass it an io.Reader.
	f, err := os.Open("path/to/file")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()
	// You can choose a name, or pass the empty string to generate a unique one.
	file, err := client.UploadFile(ctx, "", f, nil)
	if err != nil {
		log.Fatal(err)
	}
	// The return value's URI field should be passed to the model in a FileData part.
	model := client.GenerativeModel("gemini-1.5-pro")

	resp, err := model.GenerateContent(ctx, genai.FileData{URI: file.URI})
	if err != nil {
		log.Fatal(err)
	}
	_ = resp // Use resp as usual.
}

Output:

type Content 

type Content struct {
	// Ordered `Parts` that constitute a single message. Parts may have different
	// MIME types.
	Parts []Part
	// Optional. The producer of the content. Must be either 'user' or 'model'.
	//
	// Useful to set for multi-turn conversations, otherwise can be left blank
	// or unset.
	Role string
}

Content is the base structured datatype containing multi-part content of a message.

A `Content` includes a `role` field designating the producer of the `Content` and a `parts` field containing multi-part data that contains the content of the message turn.

type ContentEmbedding added in v0.2.0 

type ContentEmbedding struct {
	// The embedding values.
	Values []float32
}

ContentEmbedding is a list of floats representing an embedding.

type CountTokensResponse 

type CountTokensResponse struct {
	// The number of tokens that the `model` tokenizes the `prompt` into.
	//
	// Always non-negative.
	TotalTokens int32
}

CountTokensResponse is a response from `CountTokens`.

It returns the model's `token_count` for the `prompt`.

type EmbedContentResponse added in v0.2.0 

type EmbedContentResponse struct {
	// Output only. The embedding generated from the input content.
	Embedding *ContentEmbedding
}

EmbedContentResponse is the response to an `EmbedContentRequest`.

type EmbeddingBatch added in v0.6.0 

type EmbeddingBatch struct {
	// contains filtered or unexported fields
}

An EmbeddingBatch holds a collection of embedding requests.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	em := client.EmbeddingModel("embedding-001")
	b := em.NewBatch().
		AddContent(genai.Text("cheddar cheese")).
		AddContentWithTitle("My Cheese Report", genai.Text("I love cheddar cheese."))
	res, err := em.BatchEmbedContents(ctx, b)
	if err != nil {
		panic(err)
	}
	for _, e := range res.Embeddings {
		fmt.Println(e.Values)
	}
}

Output:

func (*EmbeddingBatch) AddContent added in v0.6.0 

func (b *EmbeddingBatch) AddContent(parts ...Part) *EmbeddingBatch

AddContent adds a content to the batch.

func (*EmbeddingBatch) AddContentWithTitle added in v0.6.0 

func (b *EmbeddingBatch) AddContentWithTitle(title string, parts ...Part) *EmbeddingBatch

AddContent adds a content to the batch with a title.

type EmbeddingModel added in v0.2.0 

type EmbeddingModel struct {

	// TaskType describes how the embedding will be used.
	TaskType TaskType
	// contains filtered or unexported fields
}

EmbeddingModel is a model that computes embeddings. Create one with Client.EmbeddingModel.

func (*EmbeddingModel) BatchEmbedContents added in v0.6.0 

func (m *EmbeddingModel) BatchEmbedContents(ctx context.Context, b *EmbeddingBatch) (*BatchEmbedContentsResponse, error)

BatchEmbedContents returns the embeddings for all the contents in the batch.

func (*EmbeddingModel) EmbedContent added in v0.2.0 

func (m *EmbeddingModel) EmbedContent(ctx context.Context, parts ...Part) (*EmbedContentResponse, error)

EmbedContent returns an embedding for the list of parts.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	em := client.EmbeddingModel("embedding-001")
	res, err := em.EmbedContent(ctx, genai.Text("cheddar cheese"))

	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.Embedding.Values)
}

Output:

func (*EmbeddingModel) EmbedContentWithTitle added in v0.2.0 

func (m *EmbeddingModel) EmbedContentWithTitle(ctx context.Context, title string, parts ...Part) (*EmbedContentResponse, error)

EmbedContentWithTitle returns an embedding for the list of parts. If the given title is non-empty, it is passed to the model and the task type is set to TaskTypeRetrievalDocument.

func (*EmbeddingModel) Info added in v0.7.0 

func (m *EmbeddingModel) Info(ctx context.Context) (*ModelInfo, error)

Info returns information about the model.

func (*EmbeddingModel) Name added in v0.6.0 

func (m *EmbeddingModel) Name() string

Name returns the name of the EmbeddingModel.

func (*EmbeddingModel) NewBatch added in v0.6.0 

func (m *EmbeddingModel) NewBatch() *EmbeddingBatch

NewBatch returns a new, empty EmbeddingBatch with the same TaskType as the model. Make multiple calls to EmbeddingBatch.AddContent or EmbeddingBatch.AddContentWithTitle. Then pass the EmbeddingBatch to EmbeddingModel.BatchEmbedContents to get all the embeddings in a single call to the model.

type File added in v0.11.0 

type File struct {
	// Immutable. Identifier. The `File` resource name. The ID (name excluding the
	// "files/" prefix) can contain up to 40 characters that are lowercase
	// alphanumeric or dashes (-). The ID cannot start or end with a dash. If the
	// name is empty on create, a unique name will be generated. Example:
	// `files/123-456`
	Name string
	// Optional. The human-readable display name for the `File`. The display name
	// must be no more than 512 characters in length, including spaces. Example:
	// "Welcome Image"
	DisplayName string
	// Output only. MIME type of the file.
	MIMEType string
	// Output only. Size of the file in bytes.
	SizeBytes int64
	// Output only. SHA-256 hash of the uploaded bytes.
	Sha256Hash []byte
	// Output only. The uri of the `File`.
	URI string
}

File is a file uploaded to the API.

type FileData added in v0.11.0 

type FileData struct {
	// Optional. The IANA standard MIME type of the source data.
	MIMEType string
	// Required. URI.
	URI string
}

FileData is URI based data.

type FileIterator added in v0.11.0 

type FileIterator struct {
	// contains filtered or unexported fields
}

A FileIterator iterates over Files.

func (*FileIterator) Next added in v0.11.0 

func (it *FileIterator) Next() (*File, error)

Next returns the next result. Its second return value is iterator.Done if there are no more results. Once Next returns Done, all subsequent calls will return Done.

func (*FileIterator) PageInfo added in v0.11.0 

func (it *FileIterator) PageInfo() *iterator.PageInfo

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

type FinishReason 

type FinishReason int32

FinishReason is defines the reason why the model stopped generating tokens. 

const (
	// FinishReasonUnspecified means default value. This value is unused.
	FinishReasonUnspecified FinishReason = 0
	// FinishReasonStop means natural stop point of the model or provided stop sequence.
	FinishReasonStop FinishReason = 1
	// FinishReasonMaxTokens means the maximum number of tokens as specified in the request was reached.
	FinishReasonMaxTokens FinishReason = 2
	// FinishReasonSafety means the candidate content was flagged for safety reasons.
	FinishReasonSafety FinishReason = 3
	// FinishReasonRecitation means the candidate content was flagged for recitation reasons.
	FinishReasonRecitation FinishReason = 4
	// FinishReasonOther means unknown reason.
	FinishReasonOther FinishReason = 5
)

func (FinishReason) String 

func (v FinishReason) String() string

type FunctionCall 

type FunctionCall struct {
	// Required. The name of the function to call.
	// Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum
	// length of 63.
	Name string
	// Optional. The function parameters and values in JSON object format.
	Args map[string]any
}

FunctionCall is a predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

type FunctionCallingConfig added in v0.11.0 

type FunctionCallingConfig struct {
	// Optional. Specifies the mode in which function calling should execute. If
	// unspecified, the default value will be set to AUTO.
	Mode FunctionCallingMode
	// Optional. A set of function names that, when provided, limits the functions
	// the model will call.
	//
	// This should only be set when the Mode is ANY. Function names
	// should match [FunctionDeclaration.name]. With mode set to ANY, model will
	// predict a function call from the set of function names provided.
	AllowedFunctionNames []string
}

FunctionCallingConfig holds configuration for function calling.

type FunctionCallingMode added in v0.11.0 

type FunctionCallingMode int32

FunctionCallingMode is defines the execution behavior for function calling by defining the execution mode. 

const (
	// FunctionCallingUnspecified means unspecified function calling mode. This value should not be used.
	FunctionCallingUnspecified FunctionCallingMode = 0
	// FunctionCallingAuto means default model behavior, model decides to predict either a function call
	// or a natural language repspose.
	FunctionCallingAuto FunctionCallingMode = 1
	// FunctionCallingAny means model is constrained to always predicting a function call only.
	// If "allowed_function_names" are set, the predicted function call will be
	// limited to any one of "allowed_function_names", else the predicted
	// function call will be any one of the provided "function_declarations".
	FunctionCallingAny FunctionCallingMode = 2
	// FunctionCallingNone means model will not predict any function call. Model behavior is same as when
	// not passing any function declarations.
	FunctionCallingNone FunctionCallingMode = 3
)

func (FunctionCallingMode) String added in v0.11.0 

func (v FunctionCallingMode) String() string

type FunctionDeclaration 

type FunctionDeclaration struct {
	// Required. The name of the function.
	// Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum
	// length of 63.
	Name string
	// Required. A brief description of the function.
	Description string
	// Optional. Describes the parameters to this function. Reflects the Open
	// API 3.03 Parameter Object string Key: the name of the parameter. Parameter
	// names are case sensitive. Schema Value: the Schema defining the type used
	// for the parameter.
	Parameters *Schema
}

FunctionDeclaration is structured representation of a function declaration as defined by the [OpenAPI 3.03 specification](https://spec.openapis.org/oas/v3.0.3). Included in this declaration are the function name and parameters. This FunctionDeclaration is a representation of a block of code that can be used as a `Tool` by the model and executed by the client.

type FunctionResponse 

type FunctionResponse struct {
	// Required. The name of the function to call.
	// Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum
	// length of 63.
	Name string
	// Required. The function response in JSON object format.
	Response map[string]any
}

FunctionResponse is the result output from a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a`FunctionCall` made based on model prediction.

type GenerateContentResponse 

type GenerateContentResponse struct {
	// Candidate responses from the model.
	Candidates []*Candidate
	// Returns the prompt's feedback related to the content filters.
	PromptFeedback *PromptFeedback
}

GenerateContentResponse is the response from a GenerateContent or GenerateContentStream call.

Note on safety ratings and content filtering. They are reported for both prompt in `GenerateContentResponse.prompt_feedback` and for each candidate in `finish_reason` and in `safety_ratings`. The API contract is that:

  • either all requested candidates are returned or no candidates at all
  • no candidates are returned only if there was something wrong with the prompt (see `prompt_feedback`)
  • feedback on each candidate is reported on `finish_reason` and `safety_ratings`.

type GenerateContentResponseIterator 

type GenerateContentResponseIterator struct {
	// contains filtered or unexported fields
}

GenerateContentResponseIterator is an iterator over GnerateContentResponse.

func (*GenerateContentResponseIterator) Next 

func (iter *GenerateContentResponseIterator) Next() (*GenerateContentResponse, error)

Next returns the next response.

type GenerationConfig 

type GenerationConfig struct {
	// Optional. Number of generated responses to return.
	//
	// Currently, this value can only be set to 1. If unset, this will default
	// to 1.
	CandidateCount *int32
	// Optional. The set of character sequences (up to 5) that will stop output
	// generation. If specified, the API will stop at the first appearance of a
	// stop sequence. The stop sequence will not be included as part of the
	// response.
	StopSequences []string
	// Optional. The maximum number of tokens to include in a candidate.
	//
	// Note: The default value varies by model, see the `Model.output_token_limit`
	// attribute of the `Model` returned from the `getModel` function.
	MaxOutputTokens *int32
	// Optional. Controls the randomness of the output.
	//
	// Note: The default value varies by model, see the `Model.temperature`
	// attribute of the `Model` returned from the `getModel` function.
	//
	// Values can range from [0.0, infinity).
	Temperature *float32
	// Optional. The maximum cumulative probability of tokens to consider when
	// sampling.
	//
	// The model uses combined Top-k and nucleus sampling.
	//
	// Tokens are sorted based on their assigned probabilities so that only the
	// most likely tokens are considered. Top-k sampling directly limits the
	// maximum number of tokens to consider, while Nucleus sampling limits number
	// of tokens based on the cumulative probability.
	//
	// Note: The default value varies by model, see the `Model.top_p`
	// attribute of the `Model` returned from the `getModel` function.
	TopP *float32
	// Optional. The maximum number of tokens to consider when sampling.
	//
	// The model uses combined Top-k and nucleus sampling.
	//
	// Top-k sampling considers the set of `top_k` most probable tokens.
	//
	// Note: The default value varies by model, see the `Model.top_k`
	// attribute of the `Model` returned from the `getModel` function.
	TopK *int32
}

GenerationConfig is configuration options for model generation and outputs. Not all parameters may be configurable for every model.

func (*GenerationConfig) SetCandidateCount added in v0.5.0 

func (c *GenerationConfig) SetCandidateCount(x int32)

SetCandidateCount sets the CandidateCount field.

func (*GenerationConfig) SetMaxOutputTokens added in v0.5.0 

func (c *GenerationConfig) SetMaxOutputTokens(x int32)

SetMaxOutputTokens sets the MaxOutputTokens field.

func (*GenerationConfig) SetTemperature added in v0.5.0 

func (c *GenerationConfig) SetTemperature(x float32)

SetTemperature sets the Temperature field.

func (*GenerationConfig) SetTopK added in v0.5.0 

func (c *GenerationConfig) SetTopK(x int32)

SetTopK sets the TopK field.

func (*GenerationConfig) SetTopP added in v0.5.0 

func (c *GenerationConfig) SetTopP(x float32)

SetTopP sets the TopP field.

type GenerativeModel 

type GenerativeModel struct {
	GenerationConfig
	SafetySettings []*SafetySetting
	Tools          []*Tool
	ToolConfig     *ToolConfig // configuration for tools
	// SystemInstruction (also known as "system prompt") is a more forceful prompt to the model.
	// The model will adhere the instructions more strongly than if they appeared in a normal prompt.
	SystemInstruction *Content
	// contains filtered or unexported fields
}

GenerativeModel is a model that can generate text. Create one with Client.GenerativeModel, then configure it by setting the exported fields.

func (*GenerativeModel) CountTokens 

func (m *GenerativeModel) CountTokens(ctx context.Context, parts ...Part) (*CountTokensResponse, error)

CountTokens counts the number of tokens in the content.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	model := client.GenerativeModel("gemini-1.0-pro")

	resp, err := model.CountTokens(ctx, genai.Text("What kind of fish is this?"))
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Num tokens:", resp.TotalTokens)
}

Output:

func (*GenerativeModel) GenerateContent 

func (m *GenerativeModel) GenerateContent(ctx context.Context, parts ...Part) (*GenerateContentResponse, error)

GenerateContent produces a single request and response.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	model := client.GenerativeModel("gemini-1.0-pro")
	resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))
	if err != nil {
		log.Fatal(err)
	}

	printResponse(resp)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:
Example (Config)

This example shows how to a configure a model. See GenerationConfig for the complete set of configuration options. 

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	model := client.GenerativeModel("gemini-1.0-pro")
	model.SetTemperature(0.9)
	model.SetTopP(0.5)
	model.SetTopK(20)
	model.SetMaxOutputTokens(100)
	model.SystemInstruction = &genai.Content{
		Parts: []genai.Part{genai.Text("You are Yoda from Star Wars.")},
	}
	resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))
	if err != nil {
		log.Fatal(err)
	}
	printResponse(resp)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:
Example (SafetySetting)

This example shows how to use SafetySettings to change the threshold for unsafe responses. 

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	model := client.GenerativeModel("gemini-1.0-pro")
	model.SafetySettings = []*genai.SafetySetting{
		{
			Category:  genai.HarmCategoryDangerousContent,
			Threshold: genai.HarmBlockLowAndAbove,
		},
		{
			Category:  genai.HarmCategoryHarassment,
			Threshold: genai.HarmBlockMediumAndAbove,
		},
	}
	resp, err := model.GenerateContent(ctx, genai.Text("I want to be bad. Please help."))
	if err != nil {
		log.Fatal(err)
	}
	printResponse(resp)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:

func (*GenerativeModel) GenerateContentStream 

func (m *GenerativeModel) GenerateContentStream(ctx context.Context, parts ...Part) *GenerateContentResponseIterator

GenerateContentStream returns an iterator that enumerates responses.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	model := client.GenerativeModel("gemini-1.0-pro")

	iter := model.GenerateContentStream(ctx, genai.Text("Tell me a story about a lumberjack and his giant ox. Keep it very short."))
	for {
		resp, err := iter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		printResponse(resp)
	}
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:
Example (Errors)

This example shows how to get more information from an error. 

package main

import (
	"context"
	"errors"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/googleapi"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}

	model := client.GenerativeModel("gemini-1.0-pro")

	iter := model.GenerateContentStream(ctx, genai.ImageData("foo", []byte("bar")))
	res, err := iter.Next()
	if err != nil {
		var gerr *googleapi.Error
		if !errors.As(err, &gerr) {
			log.Fatalf("error: %s\n", err)
		} else {
			log.Fatalf("error details: %s\n", gerr)
		}
	}
	_ = res
}

Output:

func (*GenerativeModel) Info added in v0.7.0 

func (m *GenerativeModel) Info(ctx context.Context) (*ModelInfo, error)

Info returns information about the model.

func (*GenerativeModel) StartChat 

func (m *GenerativeModel) StartChat() *ChatSession

StartChat starts a chat session.

type HarmBlockThreshold 

type HarmBlockThreshold int32

HarmBlockThreshold specifies block at and beyond a specified harm probability. 

const (
	// HarmBlockUnspecified means threshold is unspecified.
	HarmBlockUnspecified HarmBlockThreshold = 0
	// HarmBlockLowAndAbove means content with NEGLIGIBLE will be allowed.
	HarmBlockLowAndAbove HarmBlockThreshold = 1
	// HarmBlockMediumAndAbove means content with NEGLIGIBLE and LOW will be allowed.
	HarmBlockMediumAndAbove HarmBlockThreshold = 2
	// HarmBlockOnlyHigh means content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
	HarmBlockOnlyHigh HarmBlockThreshold = 3
	// HarmBlockNone means all content will be allowed.
	HarmBlockNone HarmBlockThreshold = 4
)

func (HarmBlockThreshold) String 

func (v HarmBlockThreshold) String() string

type HarmCategory 

type HarmCategory int32

HarmCategory specifies the category of a rating.

These categories cover various kinds of harms that developers may wish to adjust. 

const (
	// HarmCategoryUnspecified means category is unspecified.
	HarmCategoryUnspecified HarmCategory = 0
	// HarmCategoryDerogatory means negative or harmful comments targeting identity and/or protected attribute.
	HarmCategoryDerogatory HarmCategory = 1
	// HarmCategoryToxicity means content that is rude, disrespectful, or profane.
	HarmCategoryToxicity HarmCategory = 2
	// HarmCategoryViolence means describes scenarios depicting violence against an individual or group, or
	// general descriptions of gore.
	HarmCategoryViolence HarmCategory = 3
	// HarmCategorySexual means contains references to sexual acts or other lewd content.
	HarmCategorySexual HarmCategory = 4
	// HarmCategoryMedical means promotes unchecked medical advice.
	HarmCategoryMedical HarmCategory = 5
	// HarmCategoryDangerous means dangerous content that promotes, facilitates, or encourages harmful acts.
	HarmCategoryDangerous HarmCategory = 6
	// HarmCategoryHarassment means harasment content.
	HarmCategoryHarassment HarmCategory = 7
	// HarmCategoryHateSpeech means hate speech and content.
	HarmCategoryHateSpeech HarmCategory = 8
	// HarmCategorySexuallyExplicit means sexually explicit content.
	HarmCategorySexuallyExplicit HarmCategory = 9
	// HarmCategoryDangerousContent means dangerous content.
	HarmCategoryDangerousContent HarmCategory = 10
)

func (HarmCategory) String 

func (v HarmCategory) String() string

type HarmProbability 

type HarmProbability int32

HarmProbability specifies the probability that a piece of content is harmful.

The classification system gives the probability of the content being unsafe. This does not indicate the severity of harm for a piece of content. 

const (
	// HarmProbabilityUnspecified means probability is unspecified.
	HarmProbabilityUnspecified HarmProbability = 0
	// HarmProbabilityNegligible means content has a negligible chance of being unsafe.
	HarmProbabilityNegligible HarmProbability = 1
	// HarmProbabilityLow means content has a low chance of being unsafe.
	HarmProbabilityLow HarmProbability = 2
	// HarmProbabilityMedium means content has a medium chance of being unsafe.
	HarmProbabilityMedium HarmProbability = 3
	// HarmProbabilityHigh means content has a high chance of being unsafe.
	HarmProbabilityHigh HarmProbability = 4
)

func (HarmProbability) String 

func (v HarmProbability) String() string

type ModelInfo added in v0.7.0 

type ModelInfo struct {
	// Required. The resource name of the `Model`.
	//
	// Format: `models/{model}` with a `{model}` naming convention of:
	//
	// * "{base_model_id}-{version}"
	//
	// Examples:
	//
	// * `models/chat-bison-001`
	Name string
	// Required. The name of the base model, pass this to the generation request.
	//
	// Examples:
	//
	// * `chat-bison`
	BaseModelID string
	// Required. The version number of the model.
	//
	// This represents the major version
	Version string
	// The human-readable name of the model. E.g. "Chat Bison".
	//
	// The name can be up to 128 characters long and can consist of any UTF-8
	// characters.
	DisplayName string
	// A short description of the model.
	Description string
	// Maximum number of input tokens allowed for this model.
	InputTokenLimit int32
	// Maximum number of output tokens available for this model.
	OutputTokenLimit int32
	// The model's supported generation methods.
	//
	// The method names are defined as Pascal case
	// strings, such as `generateMessage` which correspond to API methods.
	SupportedGenerationMethods []string
	// Controls the randomness of the output.
	//
	// Values can range over `[0.0,1.0]`, inclusive. A value closer to `1.0` will
	// produce responses that are more varied, while a value closer to `0.0` will
	// typically result in less surprising responses from the model.
	// This value specifies default to be used by the backend while making the
	// call to the model.
	Temperature float32
	// For Nucleus sampling.
	//
	// Nucleus sampling considers the smallest set of tokens whose probability
	// sum is at least `top_p`.
	// This value specifies default to be used by the backend while making the
	// call to the model.
	TopP float32
	// For Top-k sampling.
	//
	// Top-k sampling considers the set of `top_k` most probable tokens.
	// This value specifies default to be used by the backend while making the
	// call to the model.
	TopK int32
}

ModelInfo is information about a language model.

type ModelInfoIterator added in v0.7.0 

type ModelInfoIterator struct {
	// contains filtered or unexported fields
}

A ModelInfoIterator iterates over Models.

func (*ModelInfoIterator) Next added in v0.7.0 

func (it *ModelInfoIterator) Next() (*ModelInfo, error)

Next returns the next result. Its second return value is iterator.Done if there are no more results. Once Next returns Done, all subsequent calls will return Done.

func (*ModelInfoIterator) PageInfo added in v0.7.0 

func (it *ModelInfoIterator) PageInfo() *iterator.PageInfo

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

type Part 

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

A Part is either a Text, a Blob or a FunctionResponse.

type PromptFeedback 

type PromptFeedback struct {
	// Optional. If set, the prompt was blocked and no candidates are returned.
	// Rephrase your prompt.
	BlockReason BlockReason
	// Ratings for safety of the prompt.
	// There is at most one rating per category.
	SafetyRatings []*SafetyRating
}

PromptFeedback contains a set of the feedback metadata the prompt specified in `GenerateContentRequest.content`.

type SafetyRating 

type SafetyRating struct {
	// Required. The category for this rating.
	Category HarmCategory
	// Required. The probability of harm for this content.
	Probability HarmProbability
	// Was this content blocked because of this rating?
	Blocked bool
}

SafetyRating is the safety rating for a piece of content.

The safety rating contains the category of harm and the harm probability level in that category for a piece of content. Content is classified for safety across a number of harm categories and the probability of the harm classification is included here.

type SafetySetting 

type SafetySetting struct {
	// Required. The category for this setting.
	Category HarmCategory
	// Required. Controls the probability threshold at which harm is blocked.
	Threshold HarmBlockThreshold
}

SafetySetting is safety setting, affecting the safety-blocking behavior.

Passing a safety setting for a category changes the allowed proability that content is blocked.

type Schema 

type Schema struct {
	// Required. Data type.
	Type Type
	// Optional. The format of the data. This is used only for primitive
	// datatypes. Supported formats:
	//
	//	for NUMBER type: float, double
	//	for INTEGER type: int32, int64
	Format string
	// Optional. A brief description of the parameter. This could contain examples
	// of use. Parameter description may be formatted as Markdown.
	Description string
	// Optional. Indicates if the value may be null.
	Nullable bool
	// Optional. Possible values of the element of Type.STRING with enum format.
	// For example we can define an Enum Direction as :
	// {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
	Enum []string
	// Optional. Schema of the elements of Type.ARRAY.
	Items *Schema
	// Optional. Properties of Type.OBJECT.
	Properties map[string]*Schema
	// Optional. Required properties of Type.OBJECT.
	Required []string
}

Schema is the `Schema` object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. Represents a select subset of an [OpenAPI 3.0 schema object](https://spec.openapis.org/oas/v3.0.3#schema).

type TaskType added in v0.2.0 

type TaskType int32

TaskType is type of task for which the embedding will be used. 

const (
	// TaskTypeUnspecified means unset value, which will default to one of the other enum values.
	TaskTypeUnspecified TaskType = 0
	// TaskTypeRetrievalQuery means specifies the given text is a query in a search/retrieval setting.
	TaskTypeRetrievalQuery TaskType = 1
	// TaskTypeRetrievalDocument means specifies the given text is a document from the corpus being searched.
	TaskTypeRetrievalDocument TaskType = 2
	// TaskTypeSemanticSimilarity means specifies the given text will be used for STS.
	TaskTypeSemanticSimilarity TaskType = 3
	// TaskTypeClassification means specifies that the given text will be classified.
	TaskTypeClassification TaskType = 4
	// TaskTypeClustering means specifies that the embeddings will be used for clustering.
	TaskTypeClustering TaskType = 5
)

func (TaskType) String added in v0.2.0 

func (v TaskType) String() string

type Text 

type Text string

A Text is a piece of text, like a question or phrase.

type Tool 

type Tool struct {
	// Optional. A list of `FunctionDeclarations` available to the model that can
	// be used for function calling.
	//
	// The model or system does not execute the function. Instead the defined
	// function may be returned as a [FunctionCall][content.part.function_call]
	// with arguments to the client side for execution. The model may decide to
	// call a subset of these functions by populating
	// [FunctionCall][content.part.function_call] in the response. The next
	// conversation turn may contain a
	// [FunctionResponse][content.part.function_response]
	// with the [content.role] "function" generation context for the next model
	// turn.
	FunctionDeclarations []*FunctionDeclaration
}

Tool details that the model may use to generate response.

A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/google/generative-ai-go/genai"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	currentWeather := func(city string) string {
		switch city {
		case "New York, NY":
			return "cold"
		case "Miami, FL":
			return "warm"
		default:
			return "unknown"
		}
	}

	// To use functions / tools, we have to first define a schema that describes
	// the function to the model. The schema is similar to OpenAPI 3.0.
	//
	// In this example, we create a single function that provides the model with
	// a weather forecast in a given location.
	schema := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"location": {
				Type:        genai.TypeString,
				Description: "The city and state, e.g. San Francisco, CA",
			},
			"unit": {
				Type: genai.TypeString,
				Enum: []string{"celsius", "fahrenheit"},
			},
		},
		Required: []string{"location"},
	}

	weatherTool := &genai.Tool{
		FunctionDeclarations: []*genai.FunctionDeclaration{{
			Name:        "CurrentWeather",
			Description: "Get the current weather in a given location",
			Parameters:  schema,
		}},
	}

	model := client.GenerativeModel("gemini-1.0-pro")

	// Before initiating a conversation, we tell the model which tools it has
	// at its disposal.
	model.Tools = []*genai.Tool{weatherTool}

	// For using tools, the chat mode is useful because it provides the required
	// chat context. A model needs to have tools supplied to it in the chat
	// history so it can use them in subsequent conversations.
	//
	// The flow of message expected here is:
	//
	// 1. We send a question to the model
	// 2. The model recognizes that it needs to use a tool to answer the question,
	//    an returns a FunctionCall response asking to use the CurrentWeather
	//    tool.
	// 3. We send a FunctionResponse message, simulating the return value of
	//    CurrentWeather for the model's query.
	// 4. The model provides its text answer in response to this message.
	session := model.StartChat()

	res, err := session.SendMessage(ctx, genai.Text("What is the weather like in New York?"))
	if err != nil {
		log.Fatal(err)
	}

	part := res.Candidates[0].Content.Parts[0]
	funcall, ok := part.(genai.FunctionCall)
	if !ok {
		log.Fatalf("expected FunctionCall: %v", part)
	}

	if funcall.Name != "CurrentWeather" {
		log.Fatalf("expected CurrentWeather: %v", funcall.Name)
	}

	// Expect the model to pass a proper string "location" argument to the tool.
	locArg, ok := funcall.Args["location"].(string)
	if !ok {
		log.Fatalf("expected string: %v", funcall.Args["location"])
	}

	weatherData := currentWeather(locArg)
	res, err = session.SendMessage(ctx, genai.FunctionResponse{
		Name: weatherTool.FunctionDeclarations[0].Name,
		Response: map[string]any{
			"weather": weatherData,
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	printResponse(res)
}

func printResponse(resp *genai.GenerateContentResponse) {
	for _, cand := range resp.Candidates {
		if cand.Content != nil {
			for _, part := range cand.Content.Parts {
				fmt.Println(part)
			}
		}
	}
	fmt.Println("---")
}

Output:

type ToolConfig added in v0.11.0 

type ToolConfig struct {
	// Optional. Function calling config.
	FunctionCallingConfig *FunctionCallingConfig
}

ToolConfig is the Tool configuration containing parameters for specifying `Tool` use in the request.

type Type 

type Type int32

Type contains the list of OpenAPI data types as defined by https://spec.openapis.org/oas/v3.0.3#data-types 

const (
	// TypeUnspecified means not specified, should not be used.
	TypeUnspecified Type = 0
	// TypeString means string type.
	TypeString Type = 1
	// TypeNumber means number type.
	TypeNumber Type = 2
	// TypeInteger means integer type.
	TypeInteger Type = 3
	// TypeBoolean means boolean type.
	TypeBoolean Type = 4
	// TypeArray means array type.
	TypeArray Type = 5
	// TypeObject means object type.
	TypeObject Type = 6
)

func (Type) String 

func (v Type) String() string

type UploadFileOptions added in v0.11.0 

type UploadFileOptions struct {
	DisplayName string // a more readable name for the file
	MIMEType    string // the MIME type of the file; if omitted, it will be inferred
}

UploadFileOptions are options for Client.UploadFile.

Source Files

View all Source files

Directories

Path Synopsis
generativelanguage/v1beta
Package generativelanguage provides access to the Generative Language API.
 Package generativelanguage provides access to the Generative Language API.
gensupport
Package gensupport is an internal implementation detail used by code generated by the google-api-go-generator tool.
 Package gensupport is an internal implementation detail used by code generated by the google-api-go-generator tool.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.