docs: Many small fixes

Google APIs · copybara-github · commit 21c206f7370e · 2024-08-16T17:58:52.000-07:00
feat: Add new PromptFeedback and FinishReason entries
feat: Add model max_temperature

PiperOrigin-RevId: 663936564
diff --git a/google/ai/generativelanguage/v1/BUILD.bazel b/google/ai/generativelanguage/v1/BUILD.bazel
@@ -335,7 +335,6 @@ load(
 
 csharp_proto_library(
     name = "generativelanguage_csharp_proto",
-    extra_opts = [],
     deps = [":generativelanguage_proto"],
 )
 
diff --git a/google/ai/generativelanguage/v1/generative_service.proto b/google/ai/generativelanguage/v1/generative_service.proto
@@ -34,13 +34,13 @@ option java_package = "com.google.ai.generativelanguage.v1";
 service GenerativeService {
   option (google.api.default_host) = "generativelanguage.googleapis.com";
 
-  // Generates a response from the model given an input
-  // `GenerateContentRequest`.
-  //
-  // Input capabilities differ between models, including tuned models. See the
-  // [model guide](https://ai.google.dev/models/gemini) and
-  // [tuning guide](https://ai.google.dev/docs/model_tuning_guidance) for
-  // details.
+  // Generates a model response given an input `GenerateContentRequest`.
+  // Refer to the [text generation
+  // guide](https://ai.google.dev/gemini-api/docs/text-generation) for detailed
+  // usage information. Input capabilities differ between models, including
+  // tuned models. Refer to the [model
+  // guide](https://ai.google.dev/gemini-api/docs/models/gemini) and [tuning
+  // guide](https://ai.google.dev/gemini-api/docs/model-tuning) for details.
   rpc GenerateContent(GenerateContentRequest)
       returns (GenerateContentResponse) {
     option (google.api.http) = {
@@ -54,8 +54,9 @@ service GenerativeService {
     option (google.api.method_signature) = "model,contents";
   }
 
-  // Generates a streamed response from the model given an input
-  // `GenerateContentRequest`.
+  // Generates a [streamed
+  // response](https://ai.google.dev/gemini-api/docs/text-generation?lang=python#generate-a-text-stream)
+  // from the model given an input `GenerateContentRequest`.
   rpc StreamGenerateContent(GenerateContentRequest)
       returns (stream GenerateContentResponse) {
     option (google.api.http) = {
@@ -65,7 +66,9 @@ service GenerativeService {
     option (google.api.method_signature) = "model,contents";
   }
 
-  // Generates an embedding from the model given an input `Content`.
+  // Generates a text embedding vector from the input `Content` using the
+  // specified [Gemini Embedding
+  // model](https://ai.google.dev/gemini-api/docs/models/gemini#text-embedding).
   rpc EmbedContent(EmbedContentRequest) returns (EmbedContentResponse) {
     option (google.api.http) = {
       post: "/v1/{model=models/*}:embedContent"
@@ -74,8 +77,9 @@ service GenerativeService {
     option (google.api.method_signature) = "model,content";
   }
 
-  // Generates multiple embeddings from the model given input text in a
-  // synchronous call.
+  // Generates multiple embedding vectors from the input `Content` which
+  // consists of a batch of strings represented as `EmbedContentRequest`
+  // objects.
   rpc BatchEmbedContents(BatchEmbedContentsRequest)
       returns (BatchEmbedContentsResponse) {
     option (google.api.http) = {
@@ -85,7 +89,9 @@ service GenerativeService {
     option (google.api.method_signature) = "model,requests";
   }
 
-  // Runs a model's tokenizer on input content and returns the token count.
+  // Runs a model's tokenizer on input `Content` and returns the token count.
+  // Refer to the [tokens guide](https://ai.google.dev/gemini-api/docs/tokens)
+  // to learn more about tokens.
   rpc CountTokens(CountTokensRequest) returns (CountTokensResponse) {
     option (google.api.http) = {
       post: "/v1/{model=models/*}:countTokens"
@@ -136,9 +142,10 @@ message GenerateContentRequest {
 
   // Required. The content of the current conversation with the model.
   //
-  // For single-turn queries, this is a single instance. For multi-turn queries,
-  // this is a repeated field that contains conversation history + latest
-  // request.
+  // For single-turn queries, this is a single instance. For multi-turn queries
+  // like [chat](https://ai.google.dev/gemini-api/docs/text-generation#chat),
+  // this is a repeated field that contains the conversation history and the
+  // latest request.
   repeated Content contents = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Optional. A list of unique `SafetySetting` instances for blocking unsafe
@@ -153,7 +160,11 @@ message GenerateContentRequest {
   // `SafetyCategory` provided in the list, the API will use the default safety
   // setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH,
   // HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT,
-  // HARM_CATEGORY_HARASSMENT are supported.
+  // HARM_CATEGORY_HARASSMENT are supported. Refer to the
+  // [guide](https://ai.google.dev/gemini-api/docs/safety-settings)
+  // for detailed information on available safety settings. Also refer to the
+  // [Safety guidance](https://ai.google.dev/gemini-api/docs/safety-guidance) to
+  // learn how to incorporate safety considerations in your AI applications.
   repeated SafetySetting safety_settings = 3
       [(google.api.field_behavior) = OPTIONAL];
 
@@ -163,7 +174,7 @@ message GenerateContentRequest {
 }
 
 // Configuration options for model generation and outputs. Not all parameters
-// may be configurable for every model.
+// are configurable for every model.
 message GenerationConfig {
   // Optional. Number of generated responses to return.
   //
@@ -173,11 +184,11 @@ message GenerationConfig {
 
   // 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
+  // `stop_sequence`. The stop sequence will not be included as part of the
   // response.
   repeated string stop_sequences = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. The maximum number of tokens to include in a candidate.
+  // Optional. The maximum number of tokens to include in a response candidate.
   //
   // Note: The default value varies by model, see the `Model.output_token_limit`
   // attribute of the `Model` returned from the `getModel` function.
@@ -194,59 +205,68 @@ message GenerationConfig {
   // Optional. The maximum cumulative probability of tokens to consider when
   // sampling.
   //
-  // The model uses combined Top-k and nucleus sampling.
+  // The model uses combined Top-k and Top-p (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.
+  // maximum number of tokens to consider, while Nucleus sampling limits the
+  // 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.
+  // Note: The default value varies by `Model` and is specified by
+  // the`Model.top_p` attribute returned from the `getModel` function. An empty
+  // `top_k` attribute indicates that the model doesn't apply top-k sampling
+  // and doesn't allow setting `top_k` on requests.
   optional float top_p = 6 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The maximum number of tokens to consider when sampling.
   //
-  // Models use nucleus sampling or combined Top-k and nucleus sampling.
-  // Top-k sampling considers the set of `top_k` most probable tokens.
-  // Models running with nucleus sampling don't allow top_k setting.
+  // Gemini models use Top-p (nucleus) sampling or a combination of Top-k and
+  // nucleus sampling. Top-k sampling considers the set of `top_k` most probable
+  // tokens. Models running with nucleus sampling don't allow top_k setting.
   //
-  // Note: The default value varies by model, see the `Model.top_k`
-  // attribute of the `Model` returned from the `getModel` function. Empty
-  // `top_k` field in `Model` indicates the model doesn't apply top-k sampling
+  // Note: The default value varies by `Model` and is specified by
+  // the`Model.top_p` attribute returned from the `getModel` function. An empty
+  // `top_k` attribute indicates that the model doesn't apply top-k sampling
   // and doesn't allow setting `top_k` on requests.
   optional int32 top_k = 7 [(google.api.field_behavior) = OPTIONAL];
 }
 
-// Response from the model supporting multiple candidates.
+// Response from the model supporting multiple candidate responses.
 //
-// Note on safety ratings and content filtering. They are reported for both
+// Safety ratings and content filtering 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
+// in `finish_reason` and in `safety_ratings`. The API:
+//  - Returns either all requested candidates or none of them
+//  - Returns no candidates at all only if there was something wrong with the
+//    prompt (check `prompt_feedback`)
+//  - Reports feedback on each candidate in `finish_reason` and
 //    `safety_ratings`.
 message GenerateContentResponse {
   // A set of the feedback metadata the prompt specified in
   // `GenerateContentRequest.content`.
   message PromptFeedback {
-    // Specifies what was the reason why prompt was blocked.
+    // Specifies the reason why the prompt was blocked.
     enum BlockReason {
       // Default value. This value is unused.
       BLOCK_REASON_UNSPECIFIED = 0;
 
-      // Prompt was blocked due to safety reasons. You can inspect
-      // `safety_ratings` to understand which safety category blocked it.
+      // Prompt was blocked due to safety reasons. Inspect `safety_ratings`
+      // to understand which safety category blocked it.
       SAFETY = 1;
 
-      // Prompt was blocked due to unknown reaasons.
+      // Prompt was blocked due to unknown reasons.
       OTHER = 2;
+
+      // Prompt was blocked due to the terms which are included from the
+      // terminology blocklist.
+      BLOCKLIST = 3;
+
+      // Prompt was blocked due to prohibited content.
+      PROHIBITED_CONTENT = 4;
     }
 
     // Optional. If set, the prompt was blocked and no candidates are returned.
-    // Rephrase your prompt.
+    // Rephrase the prompt.
     BlockReason block_reason = 1 [(google.api.field_behavior) = OPTIONAL];
 
     // Ratings for safety of the prompt.
@@ -256,13 +276,16 @@ message GenerateContentResponse {
 
   // Metadata on the generation request's token usage.
   message UsageMetadata {
-    // Number of tokens in the prompt.
+    // Number of tokens in the prompt. When `cached_content` is set, this is
+    // still the total effective prompt size meaning this includes the number of
+    // tokens in the cached content.
     int32 prompt_token_count = 1;
 
-    // Total number of tokens across the generated candidates.
+    // Total number of tokens across all the generated response candidates.
     int32 candidates_token_count = 2;
 
-    // Total token count for the generation request (prompt + candidates).
+    // Total token count for the generation request (prompt + response
+    // candidates).
     int32 total_token_count = 3;
   }
 
@@ -289,25 +312,42 @@ message Candidate {
     // The maximum number of tokens as specified in the request was reached.
     MAX_TOKENS = 2;
 
-    // The candidate content was flagged for safety reasons.
+    // The response candidate content was flagged for safety reasons.
     SAFETY = 3;
 
-    // The candidate content was flagged for recitation reasons.
+    // The response candidate content was flagged for recitation reasons.
     RECITATION = 4;
 
+    // The response candidate content was flagged for using an unsupported
+    // language.
+    LANGUAGE = 6;
+
     // Unknown reason.
     OTHER = 5;
+
+    // Token generation stopped because the content contains forbidden terms.
+    BLOCKLIST = 7;
+
+    // Token generation stopped for potentially containing prohibited content.
+    PROHIBITED_CONTENT = 8;
+
+    // Token generation stopped because the content potentially contains
+    // Sensitive Personally Identifiable Information (SPII).
+    SPII = 9;
+
+    // The function call generated by the model is invalid.
+    MALFORMED_FUNCTION_CALL = 10;
   }
 
-  // Output only. Index of the candidate in the list of candidates.
+  // Output only. Index of the candidate in the list of response candidates.
   optional int32 index = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Generated content returned from the model.
   Content content = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Optional. Output only. The reason why the model stopped generating tokens.
   //
-  // If empty, the model has not stopped generating the tokens.
+  // If empty, the model has not stopped generating tokens.
   FinishReason finish_reason = 2 [
     (google.api.field_behavior) = OPTIONAL,
     (google.api.field_behavior) = OUTPUT_ONLY
@@ -362,8 +402,8 @@ message EmbedContentRequest {
 
   // Optional. Optional reduced dimension for the output embedding. If set,
   // excessive values in the output embedding are truncated from the end.
-  // Supported by newer models since 2024, and the earlier model
-  // (`models/embedding-001`) cannot specify this value.
+  // Supported by newer models since 2024 only. You cannot set this value if
+  // using the earlier model (`models/embedding-001`).
   optional int32 output_dimensionality = 5
       [(google.api.field_behavior) = OPTIONAL];
 }
@@ -431,8 +471,14 @@ message CountTokensRequest {
   // when `generate_content_request` is set.
   repeated Content contents = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. The overall input given to the model. CountTokens will count
-  // prompt, function calling, etc.
+  // Optional. The overall input given to the `Model`. This includes the prompt
+  // as well as other model steering information like [system
+  // instructions](https://ai.google.dev/gemini-api/docs/system-instructions),
+  // and/or function declarations for [function
+  // calling](https://ai.google.dev/gemini-api/docs/function-calling).
+  // `Model`s/`Content`s and `generate_content_request`s are mutually
+  // exclusive. You can either send `Model` + `Content`s or a
+  // `generate_content_request`, but never both.
   GenerateContentRequest generate_content_request = 3
       [(google.api.field_behavior) = OPTIONAL];
 }
@@ -441,8 +487,7 @@ message CountTokensRequest {
 //
 // It returns the model's `token_count` for the `prompt`.
 message CountTokensResponse {
-  // The number of tokens that the `model` tokenizes the `prompt` into.
-  //
-  // Always non-negative.
+  // The number of tokens that the `Model` tokenizes the `prompt` into. Always
+  // non-negative.
   int32 total_tokens = 1;
 }
diff --git a/google/ai/generativelanguage/v1/model.proto b/google/ai/generativelanguage/v1/model.proto
@@ -31,30 +31,32 @@ message Model {
     pattern: "models/{model}"
   };
 
-  // Required. The resource name of the `Model`.
+  // Required. The resource name of the `Model`. Refer to [Model
+  // variants](https://ai.google.dev/gemini-api/docs/models/gemini#model-variations)
+  // for all allowed values.
   //
   // Format: `models/{model}` with a `{model}` naming convention of:
   //
   // * "{base_model_id}-{version}"
   //
   // Examples:
   //
-  // * `models/chat-bison-001`
+  // * `models/gemini-1.5-flash-001`
   string name = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Required. The name of the base model, pass this to the generation request.
   //
   // Examples:
   //
-  // * `chat-bison`
+  // * `gemini-1.5-flash`
   string base_model_id = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Required. The version number of the model.
   //
-  // This represents the major version
+  // This represents the major version (`1.0` or `1.5`)
   string version = 3 [(google.api.field_behavior) = REQUIRED];
 
-  // The human-readable name of the model. E.g. "Chat Bison".
+  // The human-readable name of the model. E.g. "Gemini 1.5 Flash".
   //
   // The name can be up to 128 characters long and can consist of any UTF-8
   // characters.
@@ -71,20 +73,24 @@ message Model {
 
   // The model's supported generation methods.
   //
-  // The method names are defined as Pascal case
-  // strings, such as `generateMessage` which correspond to API methods.
+  // The corresponding API method names are defined as Pascal case
+  // strings, such as `generateMessage` and `generateContent`.
   repeated string supported_generation_methods = 8;
 
   // 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.
+  // Values can range over `[0.0,max_temperature]`, inclusive. A higher value
+  // 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.
   optional float temperature = 9;
 
-  // For Nucleus sampling.
+  // The maximum temperature this model can use.
+  optional float max_temperature = 13;
+
+  // For [Nucleus
+  // sampling](https://ai.google.dev/gemini-api/docs/prompting-strategies#top-p).
   //
   // Nucleus sampling considers the smallest set of tokens whose probability
   // sum is at least `top_p`.
diff --git a/google/ai/generativelanguage/v1/model_service.proto b/google/ai/generativelanguage/v1/model_service.proto

Original file line number	Diff line number	Diff line change
`@@ -335,7 +335,6 @@ load(`
`335`	`335`
`336`	`336`	`csharp_proto_library(`
`337`	`337`	`name = "generativelanguage_csharp_proto",`
`338`		`- extra_opts = [],`
`339`	`338`	`deps = [":generativelanguage_proto"],`
`340`	`339`	`)`
`341`	`340`