Skip to content

Commit 59108e7

Browse files
LytkiniLytkini
Lytkini
and
Lytkini
authored
Обновление документации (#2)
* Обновление документации * Исправлено описание подключения * Исправлено описание подключения Maven --------- Co-authored-by: Lytkini <[email protected]>
1 parent 42ad9b1 commit 59108e7

File tree

4 files changed

+175
-31
lines changed

4 files changed

+175
-31
lines changed

‎README.md

+151-10
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,30 @@
1+
# GigaChat Java SDK
2+
13
GigaChat — это Java-библиотека для работы с [REST API GigaChat](https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/gigachat-api).
24

5+
Библиотека управляет авторизацией запросов и предоставляет все необходимые методы для работы с API.
6+
Кроме этого она поддерживает:
7+
8+
* [обработку потоковой передачи токенов](gigachat-java-example/src/main/java/chat/giga/CompletionStreamingExample.java);
9+
* [работу с функциями](gigachat-java-example/src/main/java/chat/giga/FunctionExample.java);
10+
* [создание эмбеддингов](gigachat-java-example/src/main/java/chat/giga/EmbeddingExample.java);
11+
* работу в синхронном или в [асинхронном режиме](gigachat-java-example/src/main/java/chat/giga/CompletionStreamingExample.java).
12+
13+
> [!TIP]
14+
> Больше примеров работы с библиотекой — в папке [gigachat-java-example](gigachat-java-example/README.md).
15+
16+
## Требования
17+
18+
Для работы библиотеки установите Java версии 17 или выше.
19+
320
## Установка
421

22+
Чтобы установить библиотеку, подключите ее в зависимости.
23+
524
### Gradle
625

726
```kotlin
8-
implementation("chat.giga:gigachat-java:0.1.1")
27+
implementation("chat.giga:gigachat-java:0.1.2")
928
```
1029

1130
### Maven
@@ -14,13 +33,10 @@ implementation("chat.giga:gigachat-java:0.1.1")
1433
<dependency>
1534
<groupId>chat.giga</groupId>
1635
<artifactId>gigachat-java</artifactId>
17-
<version>0.1.1</version>
36+
<version>0.1.2</version>
1837
</dependency>
1938
```
2039

21-
## Требования
22-
Библиотека требует Java 17 или более позднюю версию.
23-
2440
## Быстрый старт
2541

2642
Для работы с библиотекой вам понадобится ключ авторизации API.
@@ -66,20 +82,145 @@ public class CompletionExample {
6682
```
6783

6884
> [!NOTE]
69-
> Этот и другие примеры работы с библиотекой GigaChat — в папке [examples](gigachat-java-example/README.md).
85+
> Этот и другие примеры работы с библиотекой GigaChat — в папке [gigachat-java-example](gigachat-java-example/README.md).
7086
7187
## Параметры объекта GigaChatClient
7288

73-
## Способы авторизации
89+
Для работы с GigaChat используется класс GigaChatClient, который предоставляет доступ ко всем необходимым методам работы с API.
90+
91+
Подробнее о методах и параметрах класса — в [документации класса](gigachat-java/src/main/java/chat/giga/client/GigaChatClient.java).
92+
93+
## Способы аутентификации
94+
95+
Для аутентификации используется метод [`AuthClient.builder()`](gigachat-java/src/main/java/chat/giga/client/auth/AuthClient.java), который вызывается при создании экземпляра GigaChatClient и возвращает экземпляр [AuthClientBuilder](gigachat-java/src/main/java/chat/giga/client/auth/AuthClientBuilder.java)
96+
97+
Методы AuthClientBuilder позволяют выполнить аутентификацию с помощью:
98+
99+
* ключа авторизации;
100+
* токена доступа;
101+
* клиентского идентификатора (Client ID) и ключа (Client Secret);
102+
* TLS-сертификата;
103+
* имени пользователя и пароля.
104+
105+
### Аутентификация с помощью ключа авторизации
106+
107+
При аутентификации с помощью ключа авторизации в методе `scope()` нужно передать версию API, к которой будут выполняться запросы.
108+
109+
Возможные значения:
110+
111+
* `GIGACHAT_API_PERS` — версия API для физических лиц;
112+
* `GIGACHAT_API_B2B` — версия API для ИП и юрлиц при работе по предоплате.
113+
* `GIGACHAT_API_CORP` — версия API для ИП и юрлиц при работе по постоплате.
114+
115+
По умолчанию запросы передаются в версию для физических лиц.
116+
117+
```java
118+
GigaChatClient client = GigaChatClient.builder()
119+
.authClient(AuthClient.builder()
120+
.withOAuth(OAuthBuilder.builder()
121+
// Версия API
122+
.scope(Scope.GIGACHAT_API_B2B)
123+
.authKey("ключ_авторизации")
124+
.build())
125+
.build())
126+
.build();
127+
```
128+
129+
> [!TIP]
130+
> Подробно о том, как создать проект GigaChat API — в официальной документации, в разделах [Быстрый старт для физических лиц](https://developers.sber.ru/docs/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](https://developers.sber.ru/docs/ru/gigachat/legal-quickstart).
131+
132+
### Аутентификация с помощью токена доступа
133+
134+
Токен доступа (access token) получается в обмен на ключ авторизации в запросе [`POST /api/v2/oauth`](https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-token).
135+
136+
Токен действует в течение 30 минут и содержит данные о версии API, к которой предоставляется доступ, поэтому ее не нужно указывать дополнительно.
137+
138+
```java
139+
GigaChatClient client = GigaChatClient.builder()
140+
.authClient(AuthClient.builder()
141+
.withProvidedTokenAuth("токен_доступа").build())
142+
.build();
143+
```
144+
145+
### Аутентификация с помощью клиентского идентификатора и ключа
146+
147+
Как и при использовании ключа авторизации, при аутентификации с помощью Client ID и Client Secret нужно указывать версию API, к которой будут выполняться запросы.
148+
149+
```java
150+
GigaChatClient client = GigaChatClient.builder()
151+
.authClient(AuthClient.builder()
152+
.withOAuth(OAuthBuilder.builder()
153+
.scope(Scope.GIGACHAT_API_B2B)
154+
.clientId("test-client-id")
155+
.clientSecret("test-scope")
156+
.build())
157+
.build())
158+
.logRequests(true)
159+
.logResponses(true)
160+
.build();
161+
```
162+
163+
### Аутентификация с помощью имени пользователя и пароля
164+
165+
```java
166+
GigaChatClient client = GigaChatClient.builder()
167+
.authClient(AuthClient.builder()
168+
.withUserPassword(
169+
UserPasswordAuthBuilder.builder()
170+
.user("user")
171+
.password("password")
172+
.authApiUrl("https://api.ru/v1")
173+
.scope(Scope.GIGACHAT_API_PERS)
174+
.build()).build()
175+
)
176+
.build();
177+
```
178+
179+
### Аутентификация с помощью TLS-сертификата
180+
181+
```java
182+
GigaChatClient client = GigaChatClient.builder()
183+
.authClient(AuthClient.builder()
184+
.withCertificatesAuth(new JdkHttpClientBuilder()
185+
.httpClientBuilder(HttpClient.newBuilder())
186+
.ssl(SSL.builder()
187+
.truststorePassword("password")
188+
.trustStoreType("PKCS12")
189+
.truststorePath("/Users/test/ssl/client_truststore.p12")
190+
.keystorePassword("password")
191+
.keystoreType("PKCS12")
192+
.keystorePath("/Users/test/ssl/client_keystore.p12")
193+
.build())
194+
.build())
195+
.build())
196+
.build();
197+
```
74198

75199
## Установка корневого сертификата НУЦ Минцифры
76200

77201
Чтобы библиотека GigaChat могла передавать запросы в GigaChat API, вам нужно установить корневой сертификат [НУЦ Минцифры](https://developers.sber.ru/docs/ru/gigachat/certificates).
78202

79-
Для этого выполните команду:
203+
Для этого перейдите в папку `JAVA_HOME/bin` и выполните в консоли, запущенной от имени администратора, команду:
80204

81-
Запустить из `JAVA_HOME/bin`
205+
```shell
206+
keytool -importcert -storepass changeit -noprompt -alias rus_root_ca -cacerts -trustcacerts -file /<путь_к_файлу_сертификата>/russian_trusted_root_ca_pem.crt
82207
```
83-
keytool -importcert -storepass changeit -noprompt -alias rus_root_ca -cacerts -trustcacerts -file /Users/certs/russiantrustedca/russian_trusted_root_ca_pem.crt
208+
209+
При необходимости вы можете отключить проверку сертификатов.
210+
Для этого, создайте экземпляр GigaChatClient, с параметром `verifySslCerts(false)`:
211+
212+
```java
213+
GigaChatClient client = GigaChatClient.builder()
214+
// Отключение проверки сертификатов
215+
.verifySslCerts(false)
216+
.authClient(AuthClient.builder()
217+
.withOAuth(OAuthBuilder.builder()
218+
.scope(Scope.GIGACHAT_API_PERS)
219+
.authKey("ключ_авторизации")
220+
.build())
221+
.build())
222+
.build();
84223
```
85224

225+
> [!WARNING]
226+
> Отключение проверки сертификатов снижает безопасность обмена данными.

‎gigachat-java-example/README.md

+20-17
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
1-
# Примеры работы с GigaChat
2-
3-
В этом разделе вы найдете примеры работы с библиотекой GigaChat:
4-
5-
* Простой запрос на генерацию:
6-
* [версия](./src/main/java/chat/giga/CompletionExample.java) с отключенной проверкой сертификатов;
7-
8-
9-
* [Работа с чатом](./src/main/java/chat/giga/CompletionExample.java)
10-
* [Асинхронная работа с потоковой обработкой токенов](./src/main/java/chat/giga/CompletionStreamingExample.java)
11-
* [Взаимная аутентификация по протоколу TLS (mTLS)](./src/main/java/chat/giga/UseCertificateAuthExample.java)
12-
13-
14-
* [Пример получения изображения](./src/main/java/chat/giga/ImageDownloadFromCompletionsExample.java)
15-
16-
Комплексный пример, который демонстрирует работу с чатом и изображениями.
17-
1+
# Примеры работы с библиотекой GigaChat
2+
3+
В этом разделе вы найдете примеры работы с библиотекой GigaChat.
4+
5+
| Пример | Описание |
6+
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
7+
| [ModelListExample](src/main/java/chat/giga/ModelListExample.java) | Получение списка доступных [моделей](https://developers.sber.ru/docs/ru/gigachat/models) |
8+
| [CompletionExample](src/main/java/chat/giga/CompletionExample.java) | Простой запрос на генерацию |
9+
| [CompletionStreamingExample](src/main/java/chat/giga/CompletionStreamingExample.java) | Пример обработки [потоковой генерации токенов](https://developers.sber.ru/docs/ru/gigachat/api/response-token-streaming) |
10+
| [CompletionConversationExample](src/main/java/chat/giga/CompletionConversationExample.java) | Примеры работы с [историей сообщений](https://developers.sber.ru/docs/ru/gigachat/api/keeping-context) |
11+
| [UploadFileExample](src/main/java/chat/giga/UploadFileExample.java) | Загрузка файла в хранилище. О поддерживаемых типах файлов и возможных ограничениях — в [справке API](https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-file) |
12+
| [AvailableFilesExample](src/main/java/chat/giga/AvailableFilesExample.java) | Получение списка доступных в хранилище файлов |
13+
| [FileInfoExample](src/main/java/chat/giga/FileInfoExample.java) | Получение информации о сохраненном в хранилище файле |
14+
| [DownloadExample](src/main/java/chat/giga/DownloadExample.java) | Скачивание файла из хранилища |
15+
| [ImageDownloadFromCompletionsExample](src/main/java/chat/giga/ImageDownloadFromCompletionsExample.java) | Скачивание файла, созданного в результате запроса на генерацию |
16+
| [FileDeletedExample](src/main/java/chat/giga/FileDeletedExample.java) | Удаление файла из хранилища |
17+
| [FunctionExample](src/main/java/chat/giga/FunctionExample.java) | Пример [работы с функциями](https://developers.sber.ru/docs/ru/gigachat/api/function-calling) |
18+
| [EmbeddingExample](src/main/java/chat/giga/EmbeddingExample.java) | Создание [векторного представления текста](https://developers.sber.ru/docs/ru/gigachat/api/embeddings) |
19+
| [UseCertificateAuthExample](src/main/java/chat/giga/UseCertificateAuthExample.java) | Пример аутентификации с помощью TLS-сертификатов |
20+
| [UseUserPasswordAuthExample](src/main/java/chat/giga/UseUserPasswordAuthExample.java) | Пример аутентификации с помощью имени пользователя и пароля |

‎gigachat-java/src/main/java/chat/giga/client/GigaChatClient.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ public interface GigaChatClient {
3434
CompletionResponse completions(CompletionRequest request);
3535

3636
/**
37-
* Создать эмбендинг
37+
* Создать эмбеддинг
3838
*
39-
* @param request описание запроса на получения эмбендинга
39+
* @param request описание запроса на получения эмбеддинга
4040
* @return векторные представления соответствующих текстовых запросов. Векторное представление выглядит как массив
4141
* чисел `embedding`. Каждое значение в массиве представляет одну из характеристик или признаков текста, учтенных
4242
* при вычислении эмбеддинга. Значения образуют числовое представление текста и позволяют анализировать и

‎gigachat-java/src/main/java/chat/giga/client/GigaChatClientAsync.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,9 @@ public interface GigaChatClientAsync {
4545
void completions(CompletionRequest request, ResponseHandler<CompletionChunkResponse> handler);
4646

4747
/**
48-
* Создать эмбендинг
48+
* Создать эмбеддинг
4949
*
50-
* @param request описание запроса на получения эмбендинга
50+
* @param request описание запроса на получения эмбеддинга
5151
* @return векторные представления соответствующих текстовых запросов. Векторное представление выглядит как массив
5252
* чисел `embedding`. Каждое значение в массиве представляет одну из характеристик или признаков текста, учтенных
5353
* при вычислении эмбеддинга. Значения образуют числовое представление текста и позволяют анализировать и

0 commit comments

Comments
 (0)