Go SDK

Go SDK предоставляет обёртку для операций CRUD над основными ресурсами (базы знаний, документы, сессии и др.), а также для потокового взаимодействия (SSE) при ответах на вопросы. Исходный код находится в client/ и распространяется как отдельный Go-модуль; официальная CLI и серверные компоненты повторно используют этот SDK.

Установка

Путь модуля SDK определён в client/go.mod:

module github.com/Tencent/WeKnora/client

go 1.24.2

Способ установки:

bash

go get github.com/Tencent/WeKnora/client

Импорт:

import "github.com/Tencent/WeKnora/client"

Инициализация и аутентификация

Основные типы и конструкторы определены в client/client.go.

Структура Client

type Client struct {
    baseURL       string
    httpClient    *http.Client
    streamTimeout time.Duration
    apiKey        string
    bearerToken   string
    tenantID      *uint64
}

Экземпляр создаётся с помощью NewClient(baseURL string, options ...ClientOption) *Client. Таймаут обычного запроса по умолчанию составляет 30 секунд; потоковые (SSE) запросы по умолчанию не имеют таймаута, жизненный цикл контролируется через context (если не вызван метод WithTimeout).

Доступные параметры ClientOption

Опция	Описание
`WithAPIKey(key string)`	Установка API-ключа с длительным сроком действия, отправляется в заголовке `X-API-Key`
`WithBearerToken(token string)`	Установка JWT с коротким сроком действия, отправляется в заголовке `Authorization: Bearer <token>` (обычно после успешного `Login`)
`WithToken(token string)`	Устарело (Deprecated): псевдоним `WithAPIKey` версии v0.x, будет удалён в следующем мажорном релизе
`WithTimeout(timeout time.Duration)`	Установка верхнего предела времени ожидания для обычных и потоковых запросов
`WithTransport(rt http.RoundTripper)`	Замена базового `http.RoundTripper` (для промежуточного ПО, такого как повторные попытки / трассировка / подпись); передача `nil` восстанавливает `http.DefaultTransport`
`WithTenantID(tenantID uint64)`	Добавление заголовка `X-Tenant-ID` к каждому запросу, используется только при наличии прав `CanAccessAllTenants` для явного межтенантового доступа

Пояснения к методам аутентификации

SDK поддерживает два типа учётных данных, которые могут быть настроены одновременно (на уровне HTTP приоритет имеет X-API-Key):

API Key (долгосрочный): WithAPIKey, заголовок X-API-Key;
Bearer JWT (краткосрочный): WithBearerToken, заголовок Authorization: Bearer <token>, используется совместно с методами Login / RefreshToken / GetCurrentUser из client/auth.go.

Типовой процесс JWT-авторизации (соответствует POST /api/v1/auth/login):

c := client.NewClient("http://localhost:8080")
loginResp, err := c.Login(ctx, client.LoginRequest{ /* email + пароль */ })
// Затем создание нового аутентифицированного клиента с использованием возвращённого access token
authed := client.NewClient("http://localhost:8080",
    client.WithBearerToken(loginResp.AccessToken))

Тенанты (Tenant) и внедрение заголовков

Метод applyAuthHeaders (client/client.go) автоматически внедряет в каждый запрос:

X-API-Key / Authorization (согласно конфигурации);
X-Request-ID: считывается из ctx.Value("RequestID") (тип string) для целей трассировки;
X-Tenant-ID: приоритет имеет значение "TenantID" из context (поддерживаются uint64, *uint64, числовые строки) > значение по умолчанию из WithTenantID.

Пример переопределения тенанта для одного запроса:

tenantID := uint64(10000)
ctx := context.WithValue(context.Background(), "TenantID", &tenantID)
kb, err := apiClient.GetKnowledgeBase(ctx, kbID)

Примечание: JWT и тенантовые API-ключи уже содержат идентификатор тенанта, обычные пользователи не должны устанавливать X-Tenant-ID (серверный middleware выполняет кросс-тенантовую проверку для запросов bearer, и обычные пользователи получат ошибку 403).

Аварийный доступ Raw

Client.Raw(ctx, method, path, body) (экспериментально) инициирует произвольный HTTP-запрос с настроенными заголовками аутентификации; применяется для разовых интеграций и проброса через CLI weknora api. При наличии типизированных методов следует использовать их.

Ресурсы и методы

Ниже перечислены публичные методы Client. Внутренние методы (buildRequest, doRequest, doRequestStream, processAgentSSEStream и др.) в список не включены.

Аутентификация (Auth) — `client/auth.go`

Метод	Описание
`Login`	Вход по email и паролю, возвращает JWT access/refresh токен
`GetCurrentUser`	Получение информации о текущем пользователе и его тенанте (`GET /api/v1/auth/me`)
`RefreshToken`	Обмен refresh token на новый access token
`SwitchTenant`	Переключение в указанное пространство с перевыпуском пары токенов и установкой по умолчанию для следующего входа (`POST /api/v1/auth/switch-tenant`)
`ChangePassword`	Смена текущего пароля пользователя; после успеха сервер аннулирует все сессии, вызывающая сторона должна сбросить локальные токены
`GetAuthConfig`	Чтение публичной конфигурации аутентификации: режимы регистрации, требования к сложности пароля (`GET /api/v1/auth/config`, без аутентификации)

Базы знаний (KnowledgeBase) — `client/knowledgebase.go`

Метод	Описание
`CreateKnowledgeBase`	Создание базы знаний
`GetKnowledgeBase`	Получение деталей базы знаний
`ListKnowledgeBases`	Список баз знаний
`UpdateKnowledgeBase`	Обновление базы знаний
`DeleteKnowledgeBase`	Удаление базы знаний
`ClearKnowledgeBaseContents`	Очистка содержимого
`HybridSearch`	Гибридный поиск в базе знаний (вектор + ключевые слова); принимает `ResourceURLOptions` для получения прямых ссылок на файлы
`TogglePinKnowledgeBase`	Закрепление / открепление
`ListMoveTargets`	Список доступных целей для миграции базы знаний
`CopyKnowledgeBase`	Копирование базы знаний
`DuplicateKnowledgeBase`	Дублирование (duplicate)
`GetKBCloneProgress`	Статус выполнения задачи клонирования

Знания (Knowledge) — `client/knowledge.go`

Метод	Описание
`CreateKnowledgeFromFile`	Создание знания из локального файла (multipart, поддерживает metadata, переключатели модальности, кастомные имена, каналы, переопределение настроек парсинга)
`CreateKnowledgeFromURL`	Создание из URL
`GetKnowledge`	Детали знания
`GetKnowledgeBatch`	Пакетное получение
`ListKnowledge`	Список знаний с пагинацией
`ListKnowledgeWithFilter`	Список с фильтрами (`KnowledgeListFilter`: теги, ключевые слова, тип файлов, статус парсинга, источники, диапазон дат, папки)
`DeleteKnowledge`	Удаление
`DownloadKnowledgeFile`	Скачивание исходного файла на локальный диск
`OpenKnowledgeFile`	Потоковое открытие исходного файла (возвращает имя + `io.ReadCloser`)
`DownloadKnowledgeFiles` / `OpenKnowledgeFilesArchive`	Пакетное скачивание файлов одной базы знаний в ZIP-архив / потоковое чтение (`POST /api/v1/knowledge-bases/{id}/knowledge/batch-download`; макс. 200 ID или 512 MiB; требуется роль Contributor и права записи); использует потоковый HTTP-клиент, таймаут 30 секунд не действует
`ListKnowledgeFolders` / `MoveKnowledgeToFolder` / `RenameKnowledgeFolder`	Структура папок, перемещение (путь `FolderPath` = "" для возврата в корень), переименование папки со всеми вложениями
`UpdateKnowledge`	Обновление
`ReparseKnowledge`	Повторный парсинг
`CancelKnowledgeParse`	Отмена задачи парсинга
`GetKnowledgeProcessingSpans`	Получение span-ов обработки
`UpdateImageInfo`	Обновление сведений об изображении
`CreateManualKnowledge`	Создание «ручного» (manual) знания
`UpdateManualKnowledge`	Обновление ручного знания
`FilterKnowledge`	Фильтрация по ключевым словам/типам файлов/агентам
`MoveKnowledge`	Миграция между базами знаний
`GetKnowledgeMoveProgress`	Статус задачи миграции
`PreviewKnowledgeFile`	Предпросмотр (возвращает исходный `*http.Response`)
`BatchUpdateKnowledgeTags`	Пакетное обновление тегов

Серверный API списка знаний с v0.8.2 поддерживает параметры sort_by (updated_at / created_at / file_name) и sort_order (asc / desc), по умолчанию created_at desc; структура KnowledgeListFilter эти поля пока не содержит, для кастомной сортировки используйте метод Raw, описание параметров см. в API знаний.

Блоки (Chunk) — `client/chunk.go`

Метод	Описание
`ListKnowledgeChunks`	Список блоков знания с пагинацией
`UpdateChunk`	Обновление содержимого/статуса блока
`DeleteChunk`	Удаление блока
`GetChunkByIDOnly`	Получение блока только по ID
`DeleteGeneratedQuestion`	Удаление сгенерированного вопроса
`DeleteChunksByKnowledgeID`	Удаление всех блоков для данного знания

Сессии (Session) — `client/session.go`

Метод	Описание
`CreateSession`	Создание сессии
`GetSession`	Получение сессии
`GetSessionsByTenant`	Список сессий тенанта с пагинацией
`UpdateSession`	Обновление
`DeleteSession`	Удаление
`BatchDeleteSessions`	Пакетное удаление
`GenerateTitle`	Генерация заголовка
`KnowledgeQAStream`	Потоковые ответы (SSE, см. ниже)
`ContinueStream`	Продолжение потока (при обрывах)
`StopSession`	Остановка генерации сообщения
`SearchKnowledge`	Поиск знаний

Сообщения (Message) — `client/message.go`, `client/message_suggestion.go`

Метод	Описание	Файл
`LoadMessages`	Загрузка по времени	`client/message.go`
`GetRecentMessages`	Последние N сообщений	`client/message.go`
`GetMessagesBefore`	Сообщения до указанного момента	`client/message.go`
`SearchMessages`	Поиск в истории	`client/message.go`
`GetChatHistoryKBStats`	Статистика истории по базам знаний	`client/message.go`
`DeleteMessage`	Удаление	`client/message.go`
`EnsureMessageSuggestions`	Генерация/перегенерация подсказок	`client/message_suggestion.go`
`GetMessageSuggestions`	Получение подсказок	`client/message_suggestion.go`
`RecordMessageSuggestionEvent`	Учёт кликов/показов подсказок	`client/message_suggestion.go`

Диалог с агентом (потоковый) — `client/agent.go`

Метод	Описание
`AgentQAStream`	Потоковые ответы (устарело, упрощённый интерфейс)
`AgentQAStreamWithRequest`	Потоковые ответы (полный запрос `AgentQARequest`)
`NewAgentSession`	Создание обёртки `AgentSession` (методы `Ask` / `AskWithRequest` / `GetSessionID`)

Управление агентами — `client/agent_manage.go`

Метод	Описание
`CreateAgent`	Создание агента
`ListAgents`	Список
`GetAgent`	Просмотр
`UpdateAgent`	Обновление
`DeleteAgent`	Удаление
`CopyAgent`	Копирование
`GetAgentPlaceholders`	Плейсхолдеры конфигурации
`GetSuggestedQuestions`	Предлагаемые вопросы

С версии v0.8.2 изменения в полях запросов:

UpdateAgentRequest.Avatar из string превратилось в *string: nil означает отсутствие изменений, пустая строка — очистка аватара. При обновлении SDK требуется корректировка кода (например, Avatar: &avatar).
В SuggestedQuestion добавлено поле KnowledgeID (источник). При ответе на такой вопрос в KnowledgeQARequest / AgentQARequest через QuestionOrigin (KnowledgeBaseID, KnowledgeID) можно передать источник, который будет приоритетно учитываться в поиске; поле носит рекомендательный характер.

Модели (Model) — `client/model.go`

Метод	Описание
`CreateModel`	Создание
`GetModel`	Просмотр
`ListModels`	Список
`UpdateModel`	Обновление
`DeleteModel`	Удаление
`ListModelProviders`	Список провайдеров по типам

Тенанты (Tenant) — `client/tenant.go`

Метод	Описание
`CreateTenant` / `GetTenant` / `UpdateTenant` / `DeleteTenant` / `ListTenants` / `ListAllTenants` / `SearchTenants`	CRUD тенантов
`ListTenantAPIKeys` / `CreateTenantAPIKey` / `DeleteTenantAPIKey`	Управление API-ключами
`GetTenantKV` / `UpdateTenantKV`	Конфигурация KV
`GetAPIPrincipalConfig` / `UpdateAPIPrincipalConfig` / `CreateAPIPrincipalTestToken`	Управление субъектами API

Организация и совместное использование — `client/organization.go`

Метод	Описание
`CreateOrganization`... `DeleteOrganization`	CRUD организации
`Join...` / `SubmitJoinRequest` / `RequestRoleUpgrade`	Вступление и управление ролями
`InviteMember`...	Управление приглашениями
`ShareKnowledgeBase` / `ShareAgent`...	Совместный доступ

С v0.8.2 приглашения кандидатов разрешаются строго по полному ID пространства (GET /api/v1/organizations/{id}/search-tenants?q=<ID>), поиск по именам или почте не работает. SearchUsersForInvite (обёртка search-users с параметром keyword) не будет работать, так как API ожидает параметр q. Используйте Raw вызов для поиска.

FAQ — `client/faq.go`

Метод	Описание
`ListFAQEntries`...	Методы работы с FAQ (поиск, CRUD, экспорт в CSV)

Теги (Tag) — `client/tag.go`

Метод	Описание
`ListTags` / `CreateTag` / `UpdateTag` / `DeleteTag`	Методы работы с тегами

MCP — `client/mcp_service.go`, `client/mcp_endpoint.go`

Методы для управления MCP-сервисами (CRUD, проверка соединений, метаданные) и публикации MCP-конечных точек платформы.

Инициализация и диагностика моделей — `client/initialization.go`

Методы для настройки баз знаний, проверки состояния Ollama, LLM, Embedding, Rerank и мультимодальных функций.

Системные методы (System) — `client/system.go`

Методы для получения версии, возможностей развёртывания (capabilities), статуса парсеров и хранилищ.

Другие ресурсы

Метод	Описание	Файл
`StartEvaluation` / `GetEvaluationResult`	Оценка	`client/evaluation.go`
`ListSkills`	Список навыков	`client/skill.go`
`GetWebSearchProviders`	Провайдеры поиска	`client/web_search.go`
`Raw`	Экспериментальный метод прямого HTTP-вызова	`client/client.go`

Память, навыки и личные переменные

Файл	Методы
`client/memory.go`	Работа с настройками памяти, элементами, темами, консолидация памяти
`client/skill.go`	Установка навыков песочницы, обновление окружения
`client/env_var.go`	Работа с переменными окружения навыков
`client/tenant.go`	`UpdateTenantAPIKey` (обновление полномочий без ротации токена)

Потоковые ответы (SSE)

Потоковая передача реализована через механизм колбэков: SDK парсит поток SSE, при появлении каждого кадра вызывает колбэк; при возврате ошибки колбэком поток прерывается. Размер буфера строки SSE увеличен до 4 МБ для корректной обработки больших фреймов с references.

Потоковая база знаний: `KnowledgeQAStream` (`client/session.go`)

func (c *Client) KnowledgeQAStream(
    ctx context.Context,
    sessionID string,
    request *KnowledgeQARequest,
    callback func(*StreamResponse) error,
) error

Каждый StreamResponse содержит тип (answer, references, thinking, tool_call и т.д.), контент и маркер завершения Done.

Потоковый агент: `AgentQAStreamWithRequest` (`client/agent.go`)

Метод для Agent-режима с поддержкой KnowledgeBaseIDs, WebSearchEnabled, @mention и изображений.

Обработка ошибок

HTTP: `APIError` (`client/client.go`)

Ошибки HTTP (не 2xx) возвращаются как *APIError, содержащий StatusCode и структуру code (константы ServerErrBadRequest и т.д.).

SSE: `SSEStreamError` (`client/stream_errors.go`)

При получении сервером ошибки в потоке SDK вызывает колбэк с этой ошибкой, а затем возвращает *SSEStreamError. Рекомендуется использовать errors.Is(err, client.ErrSSEStreamTerminal).

Логирование и трассировка

client/log.go использует log/slog. Для включения отладочных сообщений:

client.SetDebugLevel("debug")

Трассировка запросов через RequestID в контексте автоматически передаётся в заголовке X-Request-ID.

Примеры

Код примеров можно найти в client/example.go.

Пример 1: Создание базы знаний и загрузка файла

// См. полный пример в исходном коде

Пример 2: Потоковый диалог

// См. полный пример в исходном коде

Справочник по исходному коду

Core и ошибки: client/client.go
Аутентификация: client/auth.go
Потоки: client/session.go, client/agent.go
Логи: client/log.go
Примеры: client/example.go

Go SDK ​

Установка ​

Инициализация и аутентификация ​

Структура Client ​

Доступные параметры ClientOption ​

Пояснения к методам аутентификации ​

Тенанты (Tenant) и внедрение заголовков ​

Аварийный доступ Raw ​

Ресурсы и методы ​

Аутентификация (Auth) — client/auth.go ​

Базы знаний (KnowledgeBase) — client/knowledgebase.go ​

Знания (Knowledge) — client/knowledge.go ​

Блоки (Chunk) — client/chunk.go ​

Сессии (Session) — client/session.go ​

Сообщения (Message) — client/message.go, client/message_suggestion.go ​

Диалог с агентом (потоковый) — client/agent.go ​

Управление агентами — client/agent_manage.go ​

Модели (Model) — client/model.go ​

Тенанты (Tenant) — client/tenant.go ​

Организация и совместное использование — client/organization.go ​

FAQ — client/faq.go ​

Теги (Tag) — client/tag.go ​

MCP — client/mcp_service.go, client/mcp_endpoint.go ​

Инициализация и диагностика моделей — client/initialization.go ​

Системные методы (System) — client/system.go ​

Другие ресурсы ​

Память, навыки и личные переменные ​

Потоковые ответы (SSE) ​

Потоковая база знаний: KnowledgeQAStream (client/session.go) ​

Потоковый агент: AgentQAStreamWithRequest (client/agent.go) ​

Обработка ошибок ​

HTTP: APIError (client/client.go) ​

SSE: SSEStreamError (client/stream_errors.go) ​

Логирование и трассировка ​

Примеры ​

Пример 1: Создание базы знаний и загрузка файла ​

Пример 2: Потоковый диалог ​

Справочник по исходному коду ​