Skip to content

Commit

Permalink
docs: [vertexai]Add README section for using system-instruction. (#10835
Browse files Browse the repository at this point in the history 
)
  • Loading branch information
@ZhenyiQ
ZhenyiQ committed May 13, 2024
1 parent 1e8df46 commit 6c1087c
Showing 1 changed file with 97 additions and 37 deletions.
134 changes: 97 additions & 37 deletions java-vertexai/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Java idiomatic SDK for [Vertex AI][product-docs].
- [Product Documentation][product-docs]


## Add Dependency
## Add dependency

If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:

Expand All @@ -32,7 +32,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:
</dependency>
```

If you are using Maven without the BOM, add this to your dependencies:
If you're using Maven without the BOM, add the following to your dependencies:

<!-- {x-version-update-start:google-cloud-vertexai:released} -->

Expand All @@ -59,35 +59,48 @@ libraryDependencies += "com.google.cloud" % "google-cloud-vertexai" % "1.3.0"

## Authentication

See the [Authentication][authentication] section in the base directory's README.
To learn how to authenticate to the API, see the [Authentication][authentication].

## Authorization

The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired Vertex AI APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the Vertex AI API calls.
When a client application makes a call to the Vertex AI API, the application
must be granted the [authorization scopes][auth-scopes] that are required for
the API. Additionally, the authenticated principal must have the
[IAM role(s)][predefined-iam-roles] that are required to access the Google Cloud
resources being called.

## Getting Started

Follow the instructions in this section to get started using the Vertex AI SDK for Java.

### Prerequisites

You will need a [Google Cloud Platform Console][developer-console] project with the Vertex AI [API enabled][enable-api].
You will need to [enable billing][enable-billing] to use Google Vertex AI.
[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by
[installing the Google Cloud Command Line Interface][cloud-cli] and running the following commands in command line:
`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`.
To use the Vertex AI SDK for Java, you must have completed the following:

* [Create a Google Cloud project][create-project].
* [Enable the Vertex AI API][enable-api] for your project.
* [Enable billing][enable-billing] for your project.
* [Install the Google Cloud Command Line Interface][cloud-cli] and run the
following commands in command line:

To acquire user credentials to use for [Application Default Credentials][adc], run `gcloud auth application-default login`.
```sh
gcloud auth login &&
gcloud config set project <var>PROJECT_ID</var>
```

### Installation and setup
To acquire user credentials to use for [Application Default Credentials][adc],
run `gcloud auth application-default login`.

You'll need to obtain the `google-cloud-vertexai` library. See the [Add Dependency](#add-dependency) section
to add `google-cloud-vertexai` as a dependency in your code.
### Install and setup the SDK

## About Vertex AI
You must install the `google-cloud-vertexai` library. See the
[Add Dependency](#add-dependency) section
to learn how to add `google-cloud-vertexai` as a dependency in your code.

[Vertex AI][product-docs] is an integrated suite of machine learning tools and services for building and using ML models with AutoML or custom code. It was previously known as AI Platform. Vertex AI offers both novices and experts the best workbench for the entire machine learning development lifecycle. This SDK currently only supports Generative AI service on the Vertex AI platform. To access the full set of services on the Vertex AI, consider using the [`google-cloud-aiplatform` client libraries][aiplatform-client-libraries].
### Use the Vertex AI SDK for Java

### Vertex AI SDK
Vertex AI provides [Generative AI Studio](generative-ai-studio) that supports text generation from multi-modality input via a set of most advanced models from Google. This brings out a wide range of applications.
The following sections show you how to perform common tasks by using the
Vertex AI SDK for Java.

#### Basic Text Generation
Vertex AI SDK allows you to access the service programmatically. The following code snippet is the most basic usage of SDK
Expand Down Expand Up @@ -116,8 +129,9 @@ public class Main {
}
```

#### Text Generation with Streaming
To get a streamed output, you can use the `generateContentStream` method
#### Stream generated output

To get a streamed output, you can use the `generateContentStream` method:

```java
package <your package name>
Expand Down Expand Up @@ -178,8 +192,10 @@ public class Main {
}
```

#### Text Generation from Multi-modal Input
To generate text based on data of multiple modalities, one needs to make a `Content`, which is made easier by `ContentMaker`:
#### Generate text from multi-modal input

To generate text from a prompt that contains multiple modalities of data, use
`ContentMaker` to make a `Content`:

```java
package <your package name>;
Expand Down Expand Up @@ -260,8 +276,10 @@ public class Main {
}
```

#### Using ChatSession for Multi-turn Conversation
Yeah, we know, that isn't the most intuitive and easy way to chat with a model. Therefore we provide a `Chat` class:
#### Use `ChatSession` for multi-turn chat

The Vertex AI SDK for Java provides a `ChatSession` class that lets you easily
chat with the model:

```java
package <your package name>;
Expand Down Expand Up @@ -305,19 +323,21 @@ public class Main {
}
```

#### Generation with customized configurations
#### Update configurations

The Vertex AI SDK for Java provides configurations for customizing content
generation. You can configure options like
[GenerationConfig][generationconfig-ref] and [SafetySetting][safetysetting-ref],
or add [Tool][tool-ref] for function calling.
[GenerationConfig][generationconfig-ref], [SafetySetting][safetysetting-ref], and
[system instructions][system-instruction], or add [Tool][tool-ref] for function
calling.

You can choose between two configuration approaches: set configs during model
instantiation for consistency across all text generations, or adjust them on a
per-request basis for fine-grained control.
You can choose between two configuration approaches: 1) set configurations
during model instantiation for consistency across all text generations, or 2)
adjust them on a per-request basis for fine-grained control.

##### Model level configurations

Below is an example of configure `GenerationConfig` for a `GenerativeModel`:
```java
package <PACKAGE_NAME>
Expand Down Expand Up @@ -355,9 +375,45 @@ public class Main {
}
```

##### Request level configurations
And an example of configuring preambles as a [system instruction][system-instruction].
```java
package <your package name>
Our SDK provides fluent APIs to control request level configurations.
import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.generativeai.ContentMaker;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import java.io.IOException;
public class Main {
private static final String PROJECT_ID = <your project id>;
private static final String LOCATION = <location>;
public static void main(String[] args) throws IOException {
try (VertexAI vertexAi = new VertexAI(PROJECT_ID, LOCATION);) {
GenerativeModel model =
new GenerativeModel.Builder()
.setModelName("gemino-pro")
.setVertexAi(vertexAi)
.setSystemInstruction(
ContentMaker.fromString(
"You're a helpful assistant that starts all its answers with: \"COOL\"")
)
.build();
GenerateContentResponse response = model.generateContent("How are you?");
// Do something with the response
}
}
}
```


##### Update request-level configurations

The Vertex AI SDK for Java provides fluent APIs to control request-level
configurations.

```java
package <PACKAGE_NAME>
Expand Down Expand Up @@ -450,8 +506,9 @@ public class Main {
```


#### Using ChatSession for Function-calling
In a chat, we can also do function calling.
#### Use ChatSession for function calling

You can perfrom a function call in a `ChatSession` as follows:

```java
package <your package name>;
Expand Down Expand Up @@ -606,8 +663,10 @@ public class Main {
}
```
#### ApiEndpoint
To use a different API endpoint, one can set it when instantiating `VertexAI`.
#### Change API endpoints
To use a different API endpoint, specify the endpoint that you want to use when
you instantiate `VertexAI`:
```java
package <your package name>
Expand Down Expand Up @@ -688,7 +747,7 @@ This library follows [Semantic Versioning](http://semver.org/).
## Contributing
## Contribute to this library
Contributions to this library are always welcome and highly encouraged.
Expand Down Expand Up @@ -755,4 +814,5 @@ Java is a registered trademark of Oracle and/or its affiliates.
[generative-ai-studio]: https://cloud.google.com/generative-ai-studio?hl=en
[generationconfig-ref]: https://cloud.google.com/java/docs/reference/google-cloud-vertexai/latest/com.google.cloud.vertexai.api.GenerationConfig.Builder
[safetysetting-ref]: https://cloud.google.com/java/docs/reference/google-cloud-vertexai/latest/com.google.cloud.vertexai.api.SafetySetting.Builder
[tool-ref]: https://cloud.google.com/java/docs/reference/google-cloud-vertexai/latest/com.google.cloud.vertexai.api.Tool.Builder
[tool-ref]: https://cloud.google.com/java/docs/reference/google-cloud-vertexai/latest/com.google.cloud.vertexai.api.Tool.Builder
[system-instruction]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/system-instructions

0 comments on commit 6c1087c

Please sign in to comment.