Documentation
¶
Overview ¶
Package vertexai exposes Google Gen AI capabilities through Vertex AI's GCP backend and Application Default Credentials.
Chat, transcription, speech, and text embedding share the official Google Gen AI SDK protocol mappers with package google while supplying genai.BackendVertexAI, project, and location. Image generation has its own adapter because the current Vertex contract is GenerateContent with Gemini image models, whereas the public Gemini Developer API now recommends the Interactions API. Treating those two transports as interchangeable would leak backend details and preserve deprecated Imagen behavior. Native chat request extensions use SDK camelCase fields. Core exclusively owns sampling, output format, reasoning effort, system messages, function tools, and tool choice; duplicate native fields are rejected. Provider-only safety, grounding, modalities, and thinking-budget fields remain available. Core ToolCall.ID is replayed unchanged on the call and its matching result, including IDs synthesized when the provider omitted one. Core Citation owns validation of native citations with a URI. Invalid citations fail Call and Stream rather than disappearing from a successful response. Citation-only chunks reach Core's accumulator, which owns text attachment. Thought signatures, including empty-text Parts, survive Core history serialization and replay in their original Part positions. Core Part.Kind owns the thought classification of visible text. Native part_state retains the independent flag on signature-only, tool, and media Parts. Stored visible-text state containing a competing thought flag is rejected. Embedding extensions use SDK camelCase fields and reject native outputDimensionality; Core embedding.Options.Dimensions owns that value.
API keys are not used. Authenticate locally with Application Default Credentials or provide an authenticated HTTP client; production workloads normally use a service account or Workload Identity.
Model availability and regions change independently on Vertex AI. Select an explicit model id and location from the current Vertex model documentation.
Constructors take a context because construction reaches the network. On the Vertex AI backend with application default credentials, building the client resolves them and then asks the resolved credential for its quota project, which is a metadata-server call the context governs — so a caller can bound or cancel its own wiring instead of a background context deciding for it.
See https://cloud.google.com/vertex-ai/generative-ai/docs.
NewSpeechModel performs unary-only Gemini 2.5 speech synthesis. Unary speech and transcription require a STOP finish reason and return the modality's ErrInvalidResponse for truncated, blocked, or unterminated output. Gemini 3.1 uses NewStreamingSpeechModel: Call aggregates Stream, and both require successful stream completion. Call discards partial audio on error. Native speech_response metadata describes the latest stream event, not a fabricated unary response. Request model overrides must stay in that capability.
Index ¶
Constants ¶
const ( Provider = "VertexAI" RequestExtensionKey = "vertexai/request" ResponseExtensionKey = "vertexai/response" SpeechRequestExtensionKey = "vertexai/speech_request" SpeechResponseExtensionKey = "vertexai/speech_response" TranscriptionRequestExtensionKey = "vertexai/transcription_request" TranscriptionResponseExtensionKey = "vertexai/transcription_response" EmbeddingRequestExtensionKey = "vertexai/embedding_request" EmbeddingResponseExtensionKey = "vertexai/embedding_response" ImageRequestExtensionKey = "vertexai/image_request" ImageResponseExtensionKey = "vertexai/image_response" ModelGemini25FlashImage = "gemini-2.5-flash-image" ModelGemini3ProImage = "gemini-3-pro-image" )
Exported identifiers keep provider-owned names and defaults out of caller literals.
const ( // LocationUSCentral1 is the global default for most generative // models (Gemini, Imagen, embedding). LocationUSCentral1 = "us-central1" // LocationGlobal is the multi-region endpoint — useful for // latency-sensitive workloads that can tolerate Google's // internal routing. LocationGlobal = "global" // LocationEuropeWest4 hosts Gemini and Imagen in the EU. LocationEuropeWest4 = "europe-west4" // LocationAsiaSoutheast1 (Singapore) hosts Gemini in APAC. LocationAsiaSoutheast1 = "asia-southeast1" // LocationAsiaNortheast1 (Tokyo) hosts Gemini in Japan. LocationAsiaNortheast1 = "asia-northeast1" )
Common Vertex AI regions. See https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations for the full list — coverage varies by model.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Chat ¶
Chat wraps this provider's protocol implementation so the wire type stays unexported. Callers depend on the Core modality contract, which lets the protocol change without breaking this module's public surface.
func NewChat ¶
func NewChat(ctx context.Context, config ChatConfig) (*Chat, error)
NewChat rejects an invalid provider binding before the first chat call.
type ChatConfig ¶
type ChatConfig struct {
Client ClientConfig
DefaultOptions corechat.Options
}
ChatConfig binds provider access and defaults shared by every chat call.
func (ChatConfig) Validate ¶
func (c ChatConfig) Validate() error
type ClientConfig ¶
ClientConfig identifies the Vertex AI project endpoint shared by every modality. HTTPClient remains caller-owned and is never closed by a model; BaseURL is reserved for compatible gateways and test servers.
func (ClientConfig) Validate ¶
func (c ClientConfig) Validate() error
type EmbeddingModel ¶
EmbeddingModel exposes the VertexAI embedding capability. Its zero value rejects calls.
func NewEmbeddingModel ¶
func NewEmbeddingModel(ctx context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)
NewEmbeddingModel rejects an invalid provider binding before the first embedding call.
type EmbeddingModelConfig ¶
type EmbeddingModelConfig struct {
Client ClientConfig
DefaultOptions embedding.Options
}
EmbeddingModelConfig binds provider access and defaults shared by every embedding call.
func (EmbeddingModelConfig) Validate ¶
func (e EmbeddingModelConfig) Validate() error
type ImageGenerationOptions ¶
type ImageGenerationOptions struct {
InputImages []*media.Media `json:"input_images,omitempty"`
AspectRatio string `json:"aspect_ratio,omitempty"`
ImageSize string `json:"image_size,omitempty"`
PersonGeneration string `json:"person_generation,omitempty"`
ProminentPeople string `json:"prominent_people,omitempty"`
OutputCompressionQuality *int32 `json:"output_compression_quality,omitzero"`
}
ImageGenerationOptions carries Vertex-specific GenerateContent controls and optional source images for editing. Store it under ImageRequestExtensionKey.
type ImageModel ¶
type ImageModel struct {
// contains filtered or unexported fields
}
ImageModel implements Gemini native image generation on Vertex AI through GenerateContent. It intentionally does not expose Imagen's Predict endpoint: Google deprecated the Imagen GA endpoints in favor of Gemini image models.
func NewImageModel ¶
func NewImageModel(ctx context.Context, config ImageModelConfig) (*ImageModel, error)
NewImageModel rejects an invalid provider binding before the first image call.
type ImageModelConfig ¶
type ImageModelConfig struct {
Client ClientConfig
DefaultOptions image.Options
}
ImageModelConfig binds provider access and defaults shared by every image call.
func (ImageModelConfig) Validate ¶
func (i ImageModelConfig) Validate() error
type SpeechModel ¶ added in v0.41.0
type SpeechModel protocol.SpeechModel
SpeechModel wraps this provider's protocol implementation so the wire type stays unexported. Callers depend on the Core modality contract, which lets the protocol change without breaking this module's public surface.
func NewSpeechModel ¶ added in v0.41.0
func NewSpeechModel(ctx context.Context, config SpeechModelConfig) (*SpeechModel, error)
NewSpeechModel rejects an invalid provider binding before the first speech call.
type SpeechModelConfig ¶ added in v0.41.0
type SpeechModelConfig struct {
Client ClientConfig
DefaultOptions speech.Options
}
SpeechModelConfig binds provider access and defaults shared by every speech call.
func (SpeechModelConfig) Validate ¶ added in v0.41.0
func (s SpeechModelConfig) Validate() error
type StreamingSpeechModel ¶ added in v0.41.0
type StreamingSpeechModel protocol.StreamingSpeechModel
StreamingSpeechModel exposes native incremental audio synthesis.
func NewStreamingSpeechModel ¶ added in v0.41.0
func NewStreamingSpeechModel(ctx context.Context, config SpeechModelConfig) (*StreamingSpeechModel, error)
type TranscriptionModel ¶ added in v0.41.0
type TranscriptionModel = callModel[transcription.Request, transcription.Response]
TranscriptionModel exposes the VertexAI transcription capability. Its zero value rejects calls.
func NewTranscriptionModel ¶ added in v0.41.0
func NewTranscriptionModel(ctx context.Context, config TranscriptionModelConfig) (*TranscriptionModel, error)
NewTranscriptionModel rejects an invalid provider binding before the first transcription call.
type TranscriptionModelConfig ¶ added in v0.41.0
type TranscriptionModelConfig struct {
Client ClientConfig
DefaultOptions transcription.Options
}
TranscriptionModelConfig binds provider access and defaults shared by every transcription call.
func (TranscriptionModelConfig) Validate ¶ added in v0.41.0
func (t TranscriptionModelConfig) Validate() error
Source Files