docs: add Chinese README translation

README_zh.md

@@ -0,0 +1,175 @@
+# dashscope-sdk-java
+
+这是 DashScope 模型的 Java SDK。
+
+## 使用方法
+
+要在您的 Java 系统中使用该 SDK，请在 pom.xml 中添加以下 Maven 依赖：
+
+```xml
+<dependency>
+    <groupId>com.alibaba</groupId>
+    <artifactId>dashscope-sdk-java</artifactId>
+    <version>{dashscope-sdk-java-version}</version>
+</dependency>
+```
+
+## 快速开始
+
+### 文本生成
+
+您可以通过以下方式创建文本生成客户端：
+
+```java
+Generation generation = new Generation();
+```
+
+文本生成接口支持流式和非流式查询。这些查询都接受 `GenerationParam` 作为输入，并返回 `GenerationResult` 作为输出。
+
+以下是各方法的使用示例，以 `qwen-turbo` 模型为例。
+
+#### 支持流式和非流式模式，通过回调接收输出
+
+```java
+import com.alibaba.dashscope.aigc.generation.Generation;
+import com.alibaba.dashscope.aigc.generation.GenerationParam;
+import com.alibaba.dashscope.aigc.generation.GenerationResult;
+import com.alibaba.dashscope.common.Message;
+import com.alibaba.dashscope.common.ResultCallback;
+import com.alibaba.dashscope.common.Role;
+import com.alibaba.dashscope.exception.ApiException;
+import com.alibaba.dashscope.utils.JsonUtils;
+import java.util.Arrays;
+
+public class Main {
+
+  public static void main(String[] args) {
+      Generation generation = new Generation();
+      GenerationParam param = GenerationParam.builder()
+          .apiKey(System.getenv("DASHSCOPE_API_KEY"))
+          .model(Generation.Models.QWEN_TURBO)
+          .messages(Arrays.asList(
+              Message.builder()
+                  .role(Role.USER.getValue())
+                  .content("Hello, how are you?").build()
+          )).build();
+
+      class ReactCallback extends ResultCallback<GenerationResult> {
+
+        @Override
+        public void onEvent(GenerationResult message) {
+          System.out.println(JsonUtils.toJson(message));
+        }
+
+        public void onComplete() {
+          // TODO 所有消息已接收
+        }
+
+        public void onError(Exception e) {
+          ApiException apiException = (ApiException) e;
+          // TODO 处理异常
+        }
+      }
+
+      generation.call(param, new ReactCallback());
+    }
+}
+```
+
+异常实例是一个 `ApiException` 实例。该异常可能包含两部分：
+
+- 一个 `Status` 实例。该实例包含 status_code（HTTP 错误码）、code（服务器错误码）、message（服务器错误信息）、请求 ID 和使用信息。
+- 如果发生异常，`ApiException` 实例可能只包含一个 `Exception` 堆栈跟踪，您可以像平常一样处理它。
+
+#### 仅流式模式，通过响应式 IO 接收
+
+```java
+import com.alibaba.dashscope.aigc.generation.Generation;
+import com.alibaba.dashscope.aigc.generation.GenerationParam;
+import com.alibaba.dashscope.aigc.generation.GenerationResult;
+import com.alibaba.dashscope.common.Message;
+import com.alibaba.dashscope.common.Role;
+import com.alibaba.dashscope.exception.ApiException;
+import com.alibaba.dashscope.exception.InputRequiredException;
+import com.alibaba.dashscope.exception.NoApiKeyException;
+import com.alibaba.dashscope.utils.JsonUtils;
+import io.reactivex.Flowable;
+import java.util.Arrays;
+
+public class Main {
+
+  public static void main(String[] args) {
+    Generation generation = new Generation();
+
+    Message systemMsg = Message.builder()
+        .role(Role.SYSTEM.getValue())
+        .content("You are a helpful assistant.")
+        .build();
+    Message userMsg = Message.builder()
+        .role(Role.USER.getValue())
+        .content("Hello!")
+        .build();
+    GenerationParam param = GenerationParam.builder()
+        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
+        .model(Generation.Models.QWEN_TURBO)
+        .messages(Arrays.asList(systemMsg, userMsg))
+        .resultFormat(GenerationParam.ResultFormat.MESSAGE)
+        .build();
+
+    try {
+      Flowable<GenerationResult> result = generation.streamCall(param);
+      result.blockingForEach(msg -> System.out.println(JsonUtils.toJson(msg)));
+    } catch (ApiException | NoApiKeyException | InputRequiredException e) {
+      System.err.println("An error occurred: " + e.getMessage());
+    }
+  }
+}
+```
+
+`streamCall` 方法接受 `GenerationParam`，并返回一个 `Flowable`，您可以通过 `blockingForEach` 获取流式结果，并通过 try-catch 块捕获异常。
+
+#### 仅非流式模式
+
+```java
+import com.alibaba.dashscope.aigc.generation.Generation;
+import com.alibaba.dashscope.aigc.generation.GenerationParam;
+import com.alibaba.dashscope.aigc.generation.GenerationResult;
+import com.alibaba.dashscope.common.Message;
+import com.alibaba.dashscope.common.Role;
+import com.alibaba.dashscope.exception.ApiException;
+import com.alibaba.dashscope.exception.InputRequiredException;
+import com.alibaba.dashscope.exception.NoApiKeyException;
+import com.alibaba.dashscope.utils.JsonUtils;
+import java.util.Arrays;
+
+public class Main {
+
+  public static void main(String[] args) {
+    Generation generation = new Generation();
+
+    Message systemMsg = Message.builder()
+        .role(Role.SYSTEM.getValue())
+        .content("You are a helpful assistant.")
+        .build();
+    Message userMsg = Message.builder()
+        .role(Role.USER.getValue())
+        .content("Hello!")
+        .build();
+    GenerationParam param = GenerationParam.builder()
+        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
+        .model(Generation.Models.QWEN_TURBO)
+        .messages(Arrays.asList(systemMsg, userMsg))
+        .resultFormat(GenerationParam.ResultFormat.MESSAGE)
+        .build();
+
+    try {
+      GenerationResult result = generation.call(param);
+      System.out.println(JsonUtils.toJson(result));
+    } catch (ApiException | NoApiKeyException | InputRequiredException e) {
+      System.err.println("An error occurred: " + e.getMessage());
+    }
+  }
+}
+```
+
+`call` 方法接受 `GenerationParam`，并返回 `GenerationResult`，您也可以通过 try-catch 块捕获异常。

src/main/java/com/alibaba/dashscope/protocol/DashScopeHeaders.java

@@ -8,8 +8,12 @@
 import com.alibaba.dashscope.utils.StringUtils;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.UUID;
 
 public final class DashScopeHeaders {
+  private static final String SDK_CLIENT = "java-sdk";
+  private static final String SDK_SESSION_ID = UUID.randomUUID().toString();
+
   public static String userAgent() {
     return userAgent(null);
   }
@@ -29,6 +33,24 @@ public static String userAgent(String customUserAgent) {
     return userAgent;
   }
 
+  /** Check if SDK tracking headers are disabled via DASHSCOPE_DISABLE_SDK_HEADERS env var. */
+  private static boolean isSdkHeadersDisabled() {
+    String disable = System.getenv("DASHSCOPE_DISABLE_SDK_HEADERS");
+    return "1".equals(disable) || "true".equalsIgnoreCase(disable);
+  }
+
+  /**
+   * Add SDK tracking headers to the given map. These headers are set first so that user-supplied
+   * customHeaders can override them.
+   */
+  private static void addSdkTrackingHeaders(Map<String, String> headers) {
+    if (!isSdkHeadersDisabled()) {
+      headers.put("x-dashscope-sdk-client", SDK_CLIENT);
+      headers.put("x-dashscope-sdk-version", Version.version);
+      headers.put("x-dashscope-sdk-session-id", SDK_SESSION_ID);
+    }
+  }
+
   public static Map<String, String> buildWebSocketHeaders(
       String apiKey, boolean isSecurityCheck, String workspace, Map<String, String> customHeaders)
       throws NoApiKeyException {
@@ -46,6 +68,7 @@ public static Map<String, String> buildWebSocketHeaders(
     Map<String, String> headers = new HashMap<>();
     headers.put("Authorization", "Bearer " + ApiKey.getApiKey(apiKey));
     headers.put("user-agent", userAgent(customUserAgent));
+    addSdkTrackingHeaders(headers);
     if (workspace != null && !workspace.isEmpty()) {
       headers.put("X-DashScope-WorkSpace", workspace);
     }
@@ -85,6 +108,7 @@ public static Map<String, String> buildHttpHeaders(
     Map<String, String> headers = new HashMap<>();
     headers.put("Authorization", "Bearer " + ApiKey.getApiKey(apiKey));
     headers.put("user-agent", userAgent(customUserAgent));
+    addSdkTrackingHeaders(headers);
     if (isSecurityCheck) {
       headers.put("X-DashScope-DataInspection", "enable");
     }