Documentation
¶
Overview ¶
Package vertex provides Google Vertex AI integration for Anthropic Claude models. It implements middleware to transform requests between Anthropic API format and Vertex AI format.
Package vertex provides Google Vertex AI integration middleware for Anthropic Claude models.
This package enables accessing Anthropic Claude models through Google Cloud Platform's Vertex AI service, which offers integration with Google Cloud IAM and billing, regional deployment options, and enterprise-grade SLAs.
Overview ¶
The Vertex AI integration consists of:
- VertexMiddleware: Request/response transformation middleware
- VertexConfig: Configuration for GCP project, region, and authentication
- AuthProvider: GCP authentication handling (bearer token, service account, ADC)
- Model mapping: Automatic conversion between Anthropic and Vertex AI model identifiers
Quick Start ¶
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
config.WithBearerToken("your-gcp-access-token")
vertexMW, err := vertex.NewVertexMiddleware(config)
if err != nil {
log.Fatal(err)
}
chain := middleware.NewMiddlewareChain()
chain.Add(vertexMW)
Authentication Methods ¶
The package supports three authentication methods:
Bearer Token:
config.WithBearerToken("ya29.c.xxxxx")
Service Account Key File:
config.WithServiceAccountFile("/path/to/key.json")
Application Default Credentials:
config.WithApplicationDefault()
Model Mapping ¶
Models are automatically mapped between Anthropic and Vertex AI formats:
- claude-3-5-sonnet-20241022 → claude-3-5-sonnet-v2@20241022
- claude-3-opus-20240229 → claude-3-opus@20240229
- claude-3-haiku-20240307 → claude-3-haiku@20240307
Custom mappings can be configured:
config.ModelVersionMap = map[string]string{
"my-model": "vertex-model@20241022",
}
Supported Regions ¶
The following GCP regions support Claude models:
- us-east5
- us-central1
- europe-west1
- asia-southeast1
Request Transformation ¶
The middleware transforms requests from Anthropic API format to Vertex AI format:
URL: https://api.anthropic.com/v1/messages → https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/anthropic/models/{model}:streamRawPredict
Authentication: Anthropic API key headers → GCP OAuth2 bearer tokens
Request body: Removes model field (included in URL for Vertex AI)
Error Handling ¶
Errors are returned for:
- Invalid configuration
- Authentication failures
- Models not available in the specified region
- Network errors
- Invalid request format
Examples ¶
See the package examples and tests for detailed usage patterns.
Requirements ¶
- Go 1.21 or later
- Valid GCP project with Vertex AI API enabled
- IAM role: roles/aiplatform.user or equivalent permissions
See Also ¶
- Google Vertex AI documentation: https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/claude
- Anthropic API documentation: https://docs.anthropic.com/
Example (AuthValidation) ¶
Example demonstrates authentication validation
package main
import (
"context"
"fmt"
"log"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
config.WithBearerToken("test-token")
vertexMW, err := vertex.NewVertexMiddleware(config)
if err != nil {
log.Fatal(err)
}
// Validate authentication
ctx := context.Background()
if err := vertexMW.ValidateAuth(ctx); err != nil {
log.Printf("Auth validation failed: %v", err)
return
}
// Get token information
authProvider := vertexMW.GetAuthProvider()
tokenInfo := authProvider.GetTokenInfo()
fmt.Printf("Auth type: %v\n", tokenInfo["auth_type"])
fmt.Printf("Has token: %v\n", tokenInfo["has_token"])
}
Output: Auth type: bearer_token Has token: true
Example (BasicUsage) ¶
Example demonstrates basic usage of Vertex AI middleware with bearer token
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"log"
"net/http/httptest"
"github.com/cecil-the-coder/ai-provider-kit/internal/common/middleware"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
// Create Vertex AI configuration
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
config.WithBearerToken("test-gcp-access-token")
// Create middleware
vertexMW, err := vertex.NewVertexMiddleware(config)
if err != nil {
log.Fatal(err)
}
// Create middleware chain
chain := middleware.NewMiddlewareChain()
chain.Add(vertexMW)
// Create a sample Anthropic API request
requestBody := map[string]interface{}{
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 1024,
"messages": []map[string]interface{}{
{"role": "user", "content": "Hello, Claude!"},
},
}
bodyBytes, _ := json.Marshal(requestBody)
req := httptest.NewRequest("POST", "https://api.anthropic.com/v1/messages", bytes.NewReader(bodyBytes))
req.Header.Set("Content-Type", "application/json")
ctx := context.Background()
// Process request through middleware
_, transformedReq, err := chain.ProcessRequest(ctx, req)
if err != nil {
log.Fatal(err)
}
fmt.Println("Request transformed successfully")
fmt.Printf("New URL contains: aiplatform.googleapis.com\n")
fmt.Printf("Authorization header set: %v\n", transformedReq.Header.Get("Authorization") != "")
}
Output: Request transformed successfully New URL contains: aiplatform.googleapis.com Authorization header set: true
Example (ConfigValidation) ¶
Example demonstrates configuration validation
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
// Valid configuration
validConfig := &vertex.VertexConfig{
ProjectID: "my-project",
Region: "us-east5",
AuthType: vertex.AuthTypeBearerToken,
BearerToken: "test-token",
}
if err := validConfig.Validate(); err == nil {
fmt.Println("Valid configuration")
}
// Invalid configuration - missing project ID
invalidConfig := &vertex.VertexConfig{
Region: "us-east5",
AuthType: vertex.AuthTypeBearerToken,
BearerToken: "test-token",
}
if err := invalidConfig.Validate(); err != nil {
fmt.Println("Invalid configuration detected")
}
}
Output: Valid configuration Invalid configuration detected
Example (CustomModelMapping) ¶
Example demonstrates custom model mapping
package main
import (
"fmt"
"log"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
config.WithBearerToken("test-token")
// Override default model mapping
config.ModelVersionMap = map[string]string{
"claude-3-5-sonnet-20241022": "my-custom-version@20241022",
"my-custom-model": "vertex-custom-model@20241022",
}
vertexMW, err := vertex.NewVertexMiddleware(config)
if err != nil {
log.Fatal(err)
}
// Get the mapped version
mappedVersion := vertexMW.GetConfig().GetModelVersion("my-custom-model")
fmt.Printf("Custom model mapped to: %s\n", mappedVersion)
}
Output: Custom model mapped to: vertex-custom-model@20241022
Example (EndpointConfiguration) ¶
Example demonstrates endpoint configuration
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
config := vertex.NewDefaultConfig("my-project", "europe-west1")
// Use default endpoint
defaultEndpoint := config.GetEndpoint()
fmt.Printf("Default endpoint: %s\n", defaultEndpoint)
// Use custom endpoint
config.Endpoint = "https://custom-vertex-endpoint.example.com"
customEndpoint := config.GetEndpoint()
fmt.Printf("Custom endpoint: %s\n", customEndpoint)
}
Output: Default endpoint: https://europe-west1-aiplatform.googleapis.com Custom endpoint: https://custom-vertex-endpoint.example.com
Example (HttpClient) ¶
Example demonstrates using with HTTP client
package main
import (
"fmt"
"log"
"net/http"
"github.com/cecil-the-coder/ai-provider-kit/internal/common/middleware"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
// Create configuration
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
config.WithBearerToken("test-token")
// Create middleware
vertexMW, err := vertex.NewVertexMiddleware(config)
if err != nil {
log.Fatal(err)
}
// Create HTTP client with middleware
chain := middleware.NewMiddlewareChain()
chain.Add(vertexMW)
// Create custom transport that uses the middleware
transport := &http.Transport{}
client := &http.Client{
Transport: &middlewareTransport{
chain: chain,
transport: transport,
},
}
// Use the client (would make actual HTTP request)
_ = client
fmt.Println("HTTP client configured with Vertex AI middleware")
}
// middlewareTransport is a custom HTTP transport that applies middleware
type middlewareTransport struct {
chain middleware.MiddlewareChain
transport http.RoundTripper
}
func (t *middlewareTransport) RoundTrip(req *http.Request) (*http.Response, error) {
ctx, modifiedReq, err := t.chain.ProcessRequest(req.Context(), req)
if err != nil {
return nil, err
}
resp, err := t.transport.RoundTrip(modifiedReq)
if err != nil {
return nil, err
}
_, modifiedResp, err := t.chain.ProcessResponse(ctx, modifiedReq, resp)
if err != nil {
return nil, err
}
return modifiedResp, nil
}
Output: HTTP client configured with Vertex AI middleware
Example (ModelAvailability) ¶
Example demonstrates checking model availability
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
// Check if a model is available in a specific region
modelID := "claude-3-5-sonnet-v2@20241022"
region := "us-east5"
if vertex.IsModelAvailableInRegion(modelID, region) {
fmt.Printf("%s is available in %s\n", modelID, region)
}
// Get all regions where a model is available
availableRegions := vertex.GetAvailableRegions(modelID)
fmt.Printf("Available in %d regions\n", len(availableRegions))
// Get recommended region
recommended := vertex.GetRecommendedRegion()
fmt.Printf("Recommended region: %s\n", recommended)
}
Output: claude-3-5-sonnet-v2@20241022 is available in us-east5 Available in 4 regions Recommended region: us-east5
Example (ModelConversion) ¶
Example demonstrates model ID conversion
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
// Convert Anthropic model ID to Vertex AI format
anthropicModel := "claude-3-5-sonnet-20241022"
vertexModel := vertex.GetDefaultModelVersion(anthropicModel)
fmt.Printf("Anthropic: %s -> Vertex: %s\n", anthropicModel, vertexModel)
// Convert back from Vertex to Anthropic format
convertedBack := vertex.GetAnthropicModelID(vertexModel)
fmt.Printf("Vertex: %s -> Anthropic: %s\n", vertexModel, convertedBack)
}
Output: Anthropic: claude-3-5-sonnet-20241022 -> Vertex: claude-3-5-sonnet-v2@20241022 Vertex: claude-3-5-sonnet-v2@20241022 -> Anthropic: claude-3-5-sonnet-20241022
Example (ServiceAccount) ¶
Example demonstrates service account authentication
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
config := vertex.NewDefaultConfig("my-gcp-project", "us-east5")
// Option 1: From file
config.WithServiceAccountFile("/path/to/service-account.json")
// Option 2: From JSON string
//nolint:gosec // G101: example test data, not real credentials
serviceAccountJSON := `{
"type": "service_account",
"project_id": "my-project",
"private_key_id": "key-id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"client_email": "[email protected]"
}`
config.WithServiceAccountJSON(serviceAccountJSON)
_, err := vertex.NewVertexMiddleware(config)
if err != nil {
// Expected to fail with fake credentials
fmt.Println("Service account setup (would work with real credentials)")
return
}
}
Output: Service account setup (would work with real credentials)
Example (SupportedRegions) ¶
Example demonstrates supported regions
package main
import (
"fmt"
"github.com/cecil-the-coder/ai-provider-kit/pkg/providers/anthropic/vertex"
)
func main() {
regions := vertex.SupportedRegions()
fmt.Printf("Supported regions: %d\n", len(regions))
// Note: Order may vary due to map iteration
if len(regions) == 4 {
fmt.Println("Regions include: us-east5, europe-west1, us-central1, asia-southeast1")
}
}
Output: Supported regions: 4 Regions include: us-east5, europe-west1, us-central1, asia-southeast1
Index ¶
- Variables
- func GetAnthropicModelID(vertexModelID string) string
- func GetAvailableRegions(vertexModelID string) []string
- func GetDefaultModelVersion(anthropicModelID string) string
- func GetRecommendedRegion() string
- func IsModelAvailableInRegion(vertexModelID, region string) bool
- func SupportedRegions() []string
- type AuthProvider
- func (a *AuthProvider) GetToken(ctx context.Context) (*oauth2.Token, error)
- func (a *AuthProvider) GetTokenInfo() map[string]interface{}
- func (a *AuthProvider) IsTokenExpired() bool
- func (a *AuthProvider) RefreshToken(ctx context.Context) error
- func (a *AuthProvider) SetAuthHeader(ctx context.Context, req *http.Request) error
- func (a *AuthProvider) ValidateToken(ctx context.Context) error
- type AuthType
- type VertexConfig
- func (c *VertexConfig) GetEndpoint() string
- func (c *VertexConfig) GetModelVersion(anthropicModelID string) string
- func (c *VertexConfig) Validate() error
- func (c *VertexConfig) WithApplicationDefault() *VertexConfig
- func (c *VertexConfig) WithBearerToken(token string) *VertexConfig
- func (c *VertexConfig) WithServiceAccountFile(filePath string) *VertexConfig
- func (c *VertexConfig) WithServiceAccountJSON(jsonContent string) *VertexConfig
- type VertexMiddleware
- func (m *VertexMiddleware) GetAuthProvider() *AuthProvider
- func (m *VertexMiddleware) GetConfig() *VertexConfig
- func (m *VertexMiddleware) ProcessRequest(ctx context.Context, req *http.Request) (context.Context, *http.Request, error)
- func (m *VertexMiddleware) ProcessResponse(ctx context.Context, req *http.Request, resp *http.Response) (context.Context, *http.Response, error)
- func (m *VertexMiddleware) ValidateAuth(ctx context.Context) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ModelMapping = map[string]string{
"claude-3-5-sonnet-20241022": "claude-3-5-sonnet-v2@20241022",
"claude-3-5-sonnet-20240620": "claude-3-5-sonnet@20240620",
"claude-3-5-sonnet": "claude-3-5-sonnet-v2@20241022",
"claude-3-5-haiku-20241022": "claude-3-5-haiku@20241022",
"claude-3-5-haiku": "claude-3-5-haiku@20241022",
"claude-3-opus-20240229": "claude-3-opus@20240229",
"claude-3-opus": "claude-3-opus@20240229",
"claude-3-sonnet-20240229": "claude-3-sonnet@20240229",
"claude-3-sonnet": "claude-3-sonnet@20240229",
"claude-3-haiku-20240307": "claude-3-haiku@20240307",
"claude-3-haiku": "claude-3-haiku@20240307",
}
ModelMapping defines the mapping between Anthropic model IDs and Vertex AI model identifiers
var RegionAvailability = map[string][]string{
"us-east5": {
"claude-3-5-sonnet-v2@20241022",
"claude-3-5-sonnet@20240620",
"claude-3-5-haiku@20241022",
"claude-3-opus@20240229",
"claude-3-sonnet@20240229",
"claude-3-haiku@20240307",
},
"europe-west1": {
"claude-3-5-sonnet-v2@20241022",
"claude-3-5-sonnet@20240620",
"claude-3-5-haiku@20241022",
"claude-3-opus@20240229",
"claude-3-sonnet@20240229",
"claude-3-haiku@20240307",
},
"us-central1": {
"claude-3-5-sonnet-v2@20241022",
"claude-3-5-sonnet@20240620",
"claude-3-5-haiku@20241022",
"claude-3-opus@20240229",
"claude-3-sonnet@20240229",
"claude-3-haiku@20240307",
},
"asia-southeast1": {
"claude-3-5-sonnet-v2@20241022",
"claude-3-5-sonnet@20240620",
"claude-3-5-haiku@20241022",
"claude-3-opus@20240229",
"claude-3-sonnet@20240229",
"claude-3-haiku@20240307",
},
}
RegionAvailability defines which models are available in which regions Based on Google Cloud Vertex AI Claude model availability
Functions ¶
func GetAnthropicModelID ¶
GetAnthropicModelID converts a Vertex AI model identifier back to Anthropic format Example: "claude-3-5-sonnet@20240620" -> "claude-3-5-sonnet-20240620"
func GetAvailableRegions ¶
GetAvailableRegions returns a list of regions where a model is available
func GetDefaultModelVersion ¶
GetDefaultModelVersion returns the default Vertex AI model version for an Anthropic model ID
func GetRecommendedRegion ¶
func GetRecommendedRegion() string
GetRecommendedRegion returns a recommended region based on simple heuristics This is a basic implementation that could be enhanced with latency-based selection
func IsModelAvailableInRegion ¶
IsModelAvailableInRegion checks if a model is available in a specific region
func SupportedRegions ¶
func SupportedRegions() []string
SupportedRegions returns a list of all supported regions
Types ¶
type AuthProvider ¶
type AuthProvider struct {
// contains filtered or unexported fields
}
AuthProvider handles GCP authentication for Vertex AI
func NewAuthProvider ¶
func NewAuthProvider(config *VertexConfig) (*AuthProvider, error)
NewAuthProvider creates a new authentication provider
func (*AuthProvider) GetTokenInfo ¶
func (a *AuthProvider) GetTokenInfo() map[string]interface{}
GetTokenInfo returns information about the current token
func (*AuthProvider) IsTokenExpired ¶
func (a *AuthProvider) IsTokenExpired() bool
IsTokenExpired checks if the current token is expired or about to expire
func (*AuthProvider) RefreshToken ¶
func (a *AuthProvider) RefreshToken(ctx context.Context) error
RefreshToken explicitly refreshes the token
func (*AuthProvider) SetAuthHeader ¶
SetAuthHeader sets the Authorization header on the request
func (*AuthProvider) ValidateToken ¶
func (a *AuthProvider) ValidateToken(ctx context.Context) error
ValidateToken validates that we can get a valid token
type AuthType ¶
type AuthType string
AuthType represents the type of GCP authentication
const ( // AuthTypeBearerToken uses a static bearer token for authentication AuthTypeBearerToken AuthType = "bearer_token" // AuthTypeServiceAccount uses a service account JSON key file AuthTypeServiceAccount AuthType = "service_account" // AuthTypeApplicationDefault uses Application Default Credentials (ADC) AuthTypeApplicationDefault AuthType = "adc" )
type VertexConfig ¶
type VertexConfig struct {
// ProjectID is the GCP project ID
ProjectID string `json:"project_id"`
// Region is the GCP region (e.g., "us-east5", "europe-west1")
Region string `json:"region"`
// AuthType specifies the authentication method
AuthType AuthType `json:"auth_type"`
// BearerToken is used when AuthType is AuthTypeBearerToken
BearerToken string `json:"bearer_token,omitempty"`
// ServiceAccountFile is the path to the service account JSON key file
// Used when AuthType is AuthTypeServiceAccount
ServiceAccountFile string `json:"service_account_file,omitempty"`
// ServiceAccountJSON is the raw JSON content of a service account key
// Used as an alternative to ServiceAccountFile
ServiceAccountJSON string `json:"service_account_json,omitempty"`
// ModelVersionMap allows custom mapping of Anthropic model IDs to Vertex AI versions
// Example: {"claude-3-5-sonnet-20241022": "claude-3-5-sonnet@20241022"}
ModelVersionMap map[string]string `json:"model_version_map,omitempty"`
// Endpoint is the custom Vertex AI endpoint (optional)
// If not set, will use default: https://{region}-aiplatform.googleapis.com
Endpoint string `json:"endpoint,omitempty"`
}
VertexConfig holds configuration for Google Vertex AI integration
func NewDefaultConfig ¶
func NewDefaultConfig(projectID, region string) *VertexConfig
NewDefaultConfig creates a VertexConfig with default values
func (*VertexConfig) GetEndpoint ¶
func (c *VertexConfig) GetEndpoint() string
GetEndpoint returns the Vertex AI endpoint URL
func (*VertexConfig) GetModelVersion ¶
func (c *VertexConfig) GetModelVersion(anthropicModelID string) string
GetModelVersion returns the Vertex AI model version for a given Anthropic model ID Returns the mapped version if available, otherwise returns a default mapping
func (*VertexConfig) Validate ¶
func (c *VertexConfig) Validate() error
Validate checks if the configuration is valid
func (*VertexConfig) WithApplicationDefault ¶
func (c *VertexConfig) WithApplicationDefault() *VertexConfig
WithApplicationDefault sets ADC authentication
func (*VertexConfig) WithBearerToken ¶
func (c *VertexConfig) WithBearerToken(token string) *VertexConfig
WithBearerToken sets bearer token authentication
func (*VertexConfig) WithServiceAccountFile ¶
func (c *VertexConfig) WithServiceAccountFile(filePath string) *VertexConfig
WithServiceAccountFile sets service account file authentication
func (*VertexConfig) WithServiceAccountJSON ¶
func (c *VertexConfig) WithServiceAccountJSON(jsonContent string) *VertexConfig
WithServiceAccountJSON sets service account JSON authentication
type VertexMiddleware ¶
type VertexMiddleware struct {
// contains filtered or unexported fields
}
VertexMiddleware implements request and response transformation for Vertex AI
func NewVertexMiddleware ¶
func NewVertexMiddleware(config *VertexConfig) (*VertexMiddleware, error)
NewVertexMiddleware creates a new Vertex AI middleware
func (*VertexMiddleware) GetAuthProvider ¶
func (m *VertexMiddleware) GetAuthProvider() *AuthProvider
GetAuthProvider returns the authentication provider
func (*VertexMiddleware) GetConfig ¶
func (m *VertexMiddleware) GetConfig() *VertexConfig
GetConfig returns the middleware configuration
func (*VertexMiddleware) ProcessRequest ¶
func (m *VertexMiddleware) ProcessRequest(ctx context.Context, req *http.Request) (context.Context, *http.Request, error)
ProcessRequest transforms the request from Anthropic format to Vertex AI format
func (*VertexMiddleware) ProcessResponse ¶
func (m *VertexMiddleware) ProcessResponse(ctx context.Context, req *http.Request, resp *http.Response) (context.Context, *http.Response, error)
ProcessResponse transforms the response from Vertex AI format back to Anthropic format
func (*VertexMiddleware) ValidateAuth ¶
func (m *VertexMiddleware) ValidateAuth(ctx context.Context) error
ValidateAuth validates that authentication is properly configured