diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 7bc0a5d1c..28befe3cd 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -2,6 +2,7 @@ import { defineConfig } from "vitepress"; import { useSidebar } from "vitepress-openapi"; import specZh from '../assets/service-api-openapi-zh.json' with { type: 'json' } import specEn from '../assets/service-api-openapi-en.json' with { type: 'json' } +import specJa from '../assets/service-api-openapi-ja.json' with { type: 'json' } const sidebarZh = useSidebar({ spec: specZh, @@ -13,6 +14,11 @@ const sidebarEn = useSidebar({ linkPrefix: '/en/tags/', }) +const sidebarJa = useSidebar({ + spec: specJa, + linkPrefix: '/ja/tags/', +}) + // https://vitepress.dev/reference/site-config export default defineConfig({ themeConfig: { @@ -585,6 +591,262 @@ export default defineConfig({ "https://github.com/langbot-app/Langbot-Wiki/edit/main/docs/:path", }, + // social links in the navbar + socialLinks: [ + { + icon: "github", + link: "https://github.com/langbot-app/LangBot", + }, + ], + }, + }, + ja: { + title: "LangBot ドキュメント", + label: "日本語", + lang: "ja", + link: "/ja/", + themeConfig: { + nav: [ + { text: "ホーム", link: "https://langbot.app" }, + { text: "マーケット", link: "https://space.langbot.app" }, + { text: "ロードマップ", link: "https://langbot.featurebase.app/roadmap" }, + ], + + sidebar: [ + { + text: "概要", + items: [ + { text: "はじめに（必読）", link: "/ja/insight/guide" }, + { text: "コミュニティリソース", link: "/ja/insight/community" }, + { text: "機能一覧", link: "/ja/insight/features" }, + ], + }, + { + text: "デプロイと使用方法", + items: [ + { + text: "LangBot をデプロイ", + collapsed: true, + items: [ + { text: "パッケージマネージャーでデプロイ", link: "/ja/deploy/langbot/package" }, + { text: "Docker でデプロイ", link: "/ja/deploy/langbot/docker" }, + { + text: "1Panel でデプロイ", + link: "/ja/deploy/langbot/one-click/1panel", + }, + { + text: "aaPanel でデプロイ", + link: "/ja/deploy/langbot/one-click/bt", + }, + { text: "手動デプロイ", link: "/ja/deploy/langbot/manual" }, + ], + }, + { + text: "ボットを設定", + collapsed: true, + link: "/ja/deploy/platforms/readme", + items: [ + { text: "Discord", link: "/ja/deploy/platforms/discord" }, + { text: "Telegram", link: "/ja/deploy/platforms/telegram" }, + { text: "Slack", link: "/ja/deploy/platforms/slack" }, + { text: "LINE", link: "/ja/deploy/platforms/line" }, + { text: "KOOK", link: "/ja/deploy/platforms/kook" }, + { text: "Lark", link: "/ja/deploy/platforms/lark" }, + { text: "DingTalk", link: "/ja/deploy/platforms/dingtalk" }, + { + text: "OneBot v11", + collapsed: true, + items: [ + { + text: "NapCat", + link: "/ja/deploy/platforms/qq/aiocqhttp/napcat", + }, + { + text: "Lagrange", + link: "/ja/deploy/platforms/qq/aiocqhttp/lagrange", + }, + { + text: "llonebot", + link: "/ja/deploy/platforms/qq/aiocqhttp/llonebot", + }, + ], + }, + { + text: "QQ 公式ボット", + collapsed: true, + items: [ + { + text: "Webhook 方式", + link: "/ja/deploy/platforms/qq/official_webhook", + }, + { + text: "WebSocket 方式", + link: "/ja/deploy/platforms/qq/official", + }, + ], + }, + { + text: "WeCom（企業微信）", + collapsed: true, + items: [ + { + text: "内部アプリケーション", + link: "/ja/deploy/platforms/wecom/wecom", + }, + { + text: "外部カスタマーサービス", + link: "/ja/deploy/platforms/wecom/wecomcs", + }, + { + text: "インテリジェントボット", + link: "/ja/deploy/platforms/wecom/wecombot", + } + ], + }, + { text: "WeChat 公式アカウント", link: "/ja/deploy/platforms/wxoa" }, + ], + }, + { + text: "モデルを設定", + link: "/ja/deploy/models/readme", + }, + { + text: "対話パイプラインを変更", + link: "/ja/deploy/pipelines/readme", + collapsed: true, + items: [ + { text: "Dify", link: "/ja/deploy/pipelines/dify" }, + { text: "n8n", link: "/ja/deploy/pipelines/n8n" }, + { text: "Langflow", link: "/ja/deploy/pipelines/langflow" }, + ], + }, + { + text: "ナレッジベースを使用", + link: "/ja/deploy/knowledge/readme", + }, + { + text: "MCP サービスを使用", + link: "/ja/deploy/mcp/readme", + }, + { + text: "システム設定", + link: "/ja/deploy/settings", + }, + { + text: "対話コマンド", + link: "/ja/deploy/command", + }, + { + text: "LangBot を更新", + link: "/ja/deploy/update", + }, + ], + }, + { + text: "プラグイン", + items: [ + { text: "プラグイン紹介", link: "/ja/plugin/plugin-intro" }, + { + text: "プラグイン開発", + collapsed: true, + items: [ + { text: "基本チュートリアル", link: "/ja/plugin/dev/tutor" }, + { text: "プラグイン設定情報を完成", link: "/ja/plugin/dev/basic-info" }, + { text: "ディレクトリ構造", link: "/ja/plugin/dev/directory-structure" }, + { + text: "コンポーネント開発", + collapsed: true, + items: [ + { text: "コンポーネントを追加", link: "/ja/plugin/dev/components/add" }, + { text: "コンポーネント：イベントリスナー", link: "/ja/plugin/dev/components/event-listener" }, + { text: "コンポーネント：コマンド", link: "/ja/plugin/dev/components/command" }, + { text: "コンポーネント：ツール", link: "/ja/plugin/dev/components/tool" }, + { text: "コンポーネント：ナレッジレトリーバー", link: "/ja/plugin/dev/components/knowledge-retriever" }, + ], + }, + { + text: "API リファレンス", + collapsed: true, + items: [ + { text: "プラグイン共通 API", link: "/ja/plugin/dev/apis/common" }, + { text: "パイプラインイベント", link: "/ja/plugin/dev/apis/pipeline-events" }, + { text: "メッセージプラットフォームエンティティ", link: "/ja/plugin/dev/apis/messages" }, + ], + }, + { text: "移行ガイド", link: "/ja/plugin/dev/migration" }, + { + text: "プラグインを配布", collapsed: true, + items: [ + { text: "マーケットプレイスに公開", link: "/ja/plugin/dev/publish/market" }, + { text: "GitHub で配布", link: "/ja/plugin/dev/publish/github" }, + ] + }, + ], + }, + { text: "システム互換性", link: "/ja/plugin/compatibility" }, + ], + }, + { + text: "ワークショップ", + items: [ + { + text: "本番環境で LangBot を使用", + collapsed: true, + items: [ + { text: "HTTP リバースプロキシの設定またはゲートウェイ経由で LangBot にアクセス", link: "/ja/workshop/production/proxy-and-ssl" }, + ], + }, + { + text: "メッセージプラットフォームアダプターの実装方法", + link: "/ja/workshop/impl-platform-adapter", + }, + { + text: "コンテナネットワーク設定の詳細", + link: "/ja/workshop/network-details", + }, + { + text: "New API を使用して複数チャネルのモデルを中継", + link: "/ja/workshop/newapi-integration" + }, + { + text: "PPIO API モデルの統合", + link: "/ja/workshop/ppio-integration" + }, + { + text: "302.AI モデルの統合", + link: "/ja/workshop/302ai-integration" + } + ], + }, + { + text: "[Beta] Service API リファレンス", + items: [ + { text: "概要", link: "/ja/tags/readme" }, + { text: "Webhooks", link: "/ja/tags/webhook" }, + ...sidebarJa.generateSidebarGroups({ + linkPrefix: '/ja/tags/', + }).map(group => ({ + ...group, + collapsed: true, + })), + ], + }, + { + text: "開発", + items: [ + { text: "開発設定", link: "/ja/develop/dev-config" }, + { text: "コンポーネントアーキテクチャ", link: "/ja/develop/comp-arch" }, + { text: "プラグインランタイム", link: "/ja/develop/plugin-runtime" }, + ], + }, + ], + + // edit link + editLink: { + pattern: + "https://github.com/langbot-app/Langbot-Wiki/edit/main/docs/:path", + }, + // social links in the navbar socialLinks: [ { diff --git a/docs/assets/service-api-openapi-ja.json b/docs/assets/service-api-openapi-ja.json new file mode 100644 index 000000000..0a197414a --- /dev/null +++ b/docs/assets/service-api-openapi-ja.json @@ -0,0 +1,3259 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "LangBot API with API Key Authentication", + "description": "LangBot External Service API Documentation. These interfaces support API key authentication for external systems to programmatically access LangBot resources.\n\n**Authentication Methods:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll interfaces in this documentation support both authentication methods.\n", + "version": "4.4.1", + "contact": { + "name": "LangBot", + "url": "https://langbot.app" + }, + "license": { + "name": "AGPL-3.0", + "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE" + } + }, + "servers": [ + { + "url": "http://localhost:5300", + "description": "Local development server" + } + ], + "tags": [ + { + "name": "Models - LLM", + "description": "Large Language Model management operations" + }, + { + "name": "Models - Embeddings", + "description": "Embedding model management operations" + }, + { + "name": "Bots", + "description": "Bot instance management operations" + }, + { + "name": "Pipelines", + "description": "Pipeline configuration management operations" + }, + { + "name": "Knowledge Bases", + "description": "Built-in knowledge base management operations" + }, + { + "name": "Files", + "description": "File upload and management operations" + }, + { + "name": "Plugins", + "description": "Plugin installation and management operations" + } + ], + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "paths": { + "/api/v1/provider/models/llm": { + "get": { + "tags": [ + "Models - LLM" + ], + "summary": "List all LLM models", + "description": "Retrieve a list of all configured LLM models", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LLMModel" + } + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + }, + "post": { + "tags": [ + "Models - LLM" + ], + "summary": "Create a new LLM model", + "description": "Create and configure a new LLM model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LLMModelCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Model created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid", + "example": "550e8400-e29b-41d4-a716-446655440000" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/api/v1/provider/models/llm/{model_uuid}": { + "get": { + "tags": [ + "Models - LLM" + ], + "summary": "Get a specific LLM model", + "description": "Retrieve details of a specific LLM model by UUID", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "model": { + "$ref": "#/components/schemas/LLMModel" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "put": { + "tags": [ + "Models - LLM" + ], + "summary": "Update an LLM model", + "description": "Update the configuration of an existing LLM model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LLMModelUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Model updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "delete": { + "tags": [ + "Models - LLM" + ], + "summary": "Delete an LLM model", + "description": "Remove an LLM model from the system", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "responses": { + "200": { + "description": "Model deleted successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/provider/models/llm/{model_uuid}/test": { + "post": { + "tags": [ + "Models - LLM" + ], + "summary": "Test an LLM model", + "description": "Test the connectivity and functionality of an LLM model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Model configuration to test" + } + } + } + }, + "responses": { + "200": { + "description": "Model test successful", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/api/v1/provider/models/embedding": { + "get": { + "tags": [ + "Models - Embedding" + ], + "summary": "List all embedding models", + "description": "Retrieve a list of all configured embedding models", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EmbeddingModel" + } + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + }, + "post": { + "tags": [ + "Models - Embedding" + ], + "summary": "Create a new embedding model", + "description": "Create and configure a new embedding model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmbeddingModelCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Model created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/v1/provider/models/embedding/{model_uuid}": { + "get": { + "tags": [ + "Models - Embedding" + ], + "summary": "Get a specific embedding model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "model": { + "$ref": "#/components/schemas/EmbeddingModel" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "put": { + "tags": [ + "Models - Embedding" + ], + "summary": "Update an embedding model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmbeddingModelUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Model updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "delete": { + "tags": [ + "Models - Embedding" + ], + "summary": "Delete an embedding model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "responses": { + "200": { + "description": "Model deleted successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/provider/models/embedding/{model_uuid}/test": { + "post": { + "tags": [ + "Models - Embedding" + ], + "summary": "Test an embedding model", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/ModelUUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "Model test successful", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/platform/bots": { + "get": { + "tags": [ + "Bots" + ], + "summary": "List all bots", + "description": "Retrieve a list of all configured bot instances", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "bots": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Bot" + } + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + }, + "post": { + "tags": [ + "Bots" + ], + "summary": "Create a new bot", + "description": "Create and configure a new bot instance", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BotCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Bot created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/v1/platform/bots/{bot_uuid}": { + "get": { + "tags": [ + "Bots" + ], + "summary": "Get a specific bot", + "description": "Retrieve details of a specific bot instance", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Bot UUID" + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "bot": { + "$ref": "#/components/schemas/Bot" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "put": { + "tags": [ + "Bots" + ], + "summary": "Update a bot", + "description": "Update the configuration of an existing bot instance", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BotUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Bot updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "delete": { + "tags": [ + "Bots" + ], + "summary": "Delete a bot", + "description": "Remove a bot instance from the system", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Bot deleted successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/platform/bots/{bot_uuid}/logs": { + "post": { + "tags": [ + "Bots" + ], + "summary": "Get bot event logs", + "description": "Retrieve event logs for a specific bot", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "from_index": { + "type": "integer", + "default": -1, + "description": "Starting index for logs (-1 for latest)" + }, + "max_count": { + "type": "integer", + "default": 10, + "description": "Maximum number of logs to retrieve" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "logs": { + "type": "array", + "items": { + "type": "object" + } + }, + "total_count": { + "type": "integer" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/v1/pipelines": { + "get": { + "tags": [ + "Pipelines" + ], + "summary": "List all pipelines", + "description": "Retrieve a list of all configured pipelines", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "sort_by", + "in": "query", + "schema": { + "type": "string", + "default": "created_at" + }, + "description": "Field to sort by" + }, + { + "name": "sort_order", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ], + "default": "DESC" + }, + "description": "Sort order" + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "pipelines": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pipeline" + } + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + }, + "post": { + "tags": [ + "Pipelines" + ], + "summary": "Create a new pipeline", + "description": "Create and configure a new pipeline", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PipelineCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Pipeline created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/v1/pipelines/_/metadata": { + "get": { + "tags": [ + "Pipelines" + ], + "summary": "Get pipeline metadata", + "description": "Retrieve metadata and configuration options for pipelines", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "configs": { + "type": "object" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + } + } + } + }, + "/api/v1/pipelines/{pipeline_uuid}": { + "get": { + "tags": [ + "Pipelines" + ], + "summary": "Get a specific pipeline", + "description": "Retrieve details of a specific pipeline", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/components/schemas/Pipeline" + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "put": { + "tags": [ + "Pipelines" + ], + "summary": "Update a pipeline", + "description": "Update the configuration of an existing pipeline", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PipelineUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Pipeline updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "delete": { + "tags": [ + "Pipelines" + ], + "summary": "Delete a pipeline", + "description": "Remove a pipeline from the system", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Pipeline deleted successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/pipelines/{pipeline_uuid}/extensions": { + "get": { + "tags": [ + "Pipelines" + ], + "summary": "Get pipeline extensions", + "description": "Retrieve extensions and plugins configured for a pipeline", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + }, + "put": { + "tags": [ + "Pipelines" + ], + "summary": "Update pipeline extensions", + "description": "Update the extensions configuration for a pipeline", + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "Extensions updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuccessResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + } + } + } + }, + "/api/v1/files/images": { + "post": { + "tags": [ + "Files" + ], + "summary": "Upload Image", + "description": "Upload image file (supports jpg, jpeg, png, gif, webp, max 10MB)", + "operationId": "uploadImage", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Image file" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upload successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_key": { + "type": "string", + "description": "File key" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/files/documents": { + "post": { + "tags": [ + "Files" + ], + "summary": "Upload Document", + "description": "Upload document file (max 10MB)", + "operationId": "uploadDocument", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Document file" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upload successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_id": { + "type": "string", + "description": "File ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins": { + "get": { + "tags": [ + "Plugins" + ], + "summary": "List All Plugins", + "description": "Get list of all installed plugins", + "operationId": "listPlugins", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "plugins": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/{author}/{plugin_name}": { + "get": { + "tags": [ + "Plugins" + ], + "summary": "Get Plugin Details", + "description": "Get details of a specific plugin", + "operationId": "getPlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin author" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin name" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "plugin": { + "type": "object" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Plugins" + ], + "summary": "Delete Plugin", + "description": "Uninstall the specified plugin", + "operationId": "deletePlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin author" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin name" + }, + { + "name": "delete_data", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + }, + "description": "Whether to delete plugin data" + } + ], + "responses": { + "200": { + "description": "Deletion task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/local": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install Plugin from Local File", + "description": "Upload and install plugin package file", + "operationId": "installPluginLocal", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Plugin package file (.lbpkg format)" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/github": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install Plugin from GitHub", + "description": "Install plugin from GitHub Release", + "operationId": "installPluginGitHub", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "asset_url" + ], + "properties": { + "asset_url": { + "type": "string", + "description": "GitHub Release asset download URL" + }, + "owner": { + "type": "string", + "description": "Repository owner" + }, + "repo": { + "type": "string", + "description": "Repository name" + }, + "release_tag": { + "type": "string", + "description": "Release tag" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/marketplace": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install from Marketplace", + "description": "Install plugin from LangBot plugin marketplace", + "operationId": "installPluginMarketplace", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "plugin_id": { + "type": "string", + "description": "Plugin ID" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/platform/bots/{bot_uuid}/send_message": { + "post": { + "tags": [ + "Bots" + ], + "summary": "Send Message", + "description": "Send a message to a specific target via the specified bot", + "operationId": "sendMessage", + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Bot UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "target_type", + "target_id", + "message_chain" + ], + "properties": { + "target_type": { + "type": "string", + "enum": [ + "person", + "group" + ], + "description": "Target type" + }, + "target_id": { + "type": "string", + "description": "Target ID (user ID or group ID)" + }, + "message_chain": { + "type": "array", + "items": { + "type": "object" + }, + "description": "Message chain (array of MessageComponent)" + } + } + }, + "examples": { + "Text Message": { + "value": { + "target_type": "group", + "target_id": "123456789", + "message_chain": [ + { + "type": "Plain", + "text": "Hello, World!" + } + ] + } + }, + "Text and Image": { + "value": { + "target_type": "person", + "target_id": "987654321", + "message_chain": [ + { + "type": "Plain", + "text": "Check out this image:" + }, + { + "type": "Image", + "url": "https://example.com/image.jpg" + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Message sent successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "sent": { + "type": "boolean", + "example": true + } + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "target_type is required" + } + } + } + } + } + }, + "500": { + "description": "Failed to send", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "Failed to send message: Bot not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Get All Knowledge Bases", + "description": "Get all builtin knowledge bases", + "operationId": "listKnowledgeBases", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "bases": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Create Knowledge Base", + "description": "Create a new knowledge base", + "operationId": "createKnowledgeBase", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name", + "embedding_model_uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "name" + }, + "description": { + "type": "string", + "description": "description" + }, + "embedding_model_uuid": { + "type": "string", + "description": "Embedding model UUID" + } + } + }, + "example": { + "name": "技术文档库", + "description": "存储技术文档和API参考", + "embedding_model_uuid": "uuid-of-embedding-model" + } + } + } + }, + "responses": { + "200": { + "description": "Knowledge base created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Get Knowledge Base Details", + "description": "Get details info of specified knowledge base", + "operationId": "getKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "base": { + "type": "object" + } + } + } + } + } + } + } + }, + "404": { + "description": "Knowledge base not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "knowledge base not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Update Knowledge Base Info", + "description": "Update knowledge base information", + "operationId": "updateKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Update successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Delete Knowledge Base", + "description": "Delete a specified knowledge base", + "operationId": "deleteKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "responses": { + "200": { + "description": "Deletion successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "List Knowledge Base Files", + "description": "Get all files in the specified knowledge base", + "operationId": "listKnowledgeBaseFiles", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Add File to Knowledge Base", + "description": "Add uploaded file to knowledge base for processing", + "operationId": "addFileToKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "file_id" + ], + "properties": { + "file_id": { + "type": "string", + "description": "File ID（从文件上传接口获取）" + } + } + }, + "example": { + "file_id": "document_abc123.pdf" + } + } + } + }, + "responses": { + "200": { + "description": "Addition successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Processing task ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { + "delete": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Delete File from Knowledge Base", + "description": "Delete file from the specified knowledge base", + "operationId": "deleteFileFromKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "File ID" + } + ], + "responses": { + "200": { + "description": "Deletion successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Retrieve Knowledge", + "description": "Search for relevant knowledge in the knowledge base", + "operationId": "retrieveKnowledge", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "Query text" + } + } + }, + "example": { + "query": "如何使用 LangBot 创建机器人？" + } + } + } + }, + "responses": { + "200": { + "description": "Retrieval successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "X-API-Key", + "description": "API Key authentication using X-API-Key header.\nExample: `X-API-Key: lbk_your_api_key_here`\n" + }, + "BearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "Bearer token authentication. Can be either a user JWT token or an API key.\nExample: `Authorization: Bearer `\n" + } + }, + "parameters": { + "ModelUUID": { + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Model UUID" + } + }, + "schemas": { + "LLMModel": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "example": "GPT-4" + }, + "description": { + "type": "string", + "example": "OpenAI GPT-4 model" + }, + "requester": { + "type": "string", + "example": "openai-chat-completions" + }, + "requester_config": { + "type": "object", + "properties": { + "model": { + "type": "string", + "example": "gpt-4" + }, + "args": { + "type": "object" + } + } + }, + "api_keys": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "keys": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "abilities": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "chat", + "vision" + ] + }, + "extra_args": { + "type": "object" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "LLMModelCreate": { + "type": "object", + "required": [ + "name", + "requester", + "requester_config", + "api_keys" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "requester": { + "type": "string" + }, + "requester_config": { + "type": "object" + }, + "api_keys": { + "type": "array", + "items": { + "type": "object" + } + }, + "abilities": { + "type": "array", + "items": { + "type": "string" + } + }, + "extra_args": { + "type": "object" + } + } + }, + "LLMModelUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "requester_config": { + "type": "object" + }, + "api_keys": { + "type": "array", + "items": { + "type": "object" + } + }, + "abilities": { + "type": "array", + "items": { + "type": "string" + } + }, + "extra_args": { + "type": "object" + } + } + }, + "EmbeddingModel": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "requester": { + "type": "string" + }, + "requester_config": { + "type": "object" + }, + "api_keys": { + "type": "array", + "items": { + "type": "object" + } + }, + "extra_args": { + "type": "object" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "EmbeddingModelCreate": { + "type": "object", + "required": [ + "name", + "requester", + "requester_config", + "api_keys" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "requester": { + "type": "string" + }, + "requester_config": { + "type": "object" + }, + "api_keys": { + "type": "array", + "items": { + "type": "object" + } + }, + "extra_args": { + "type": "object" + } + } + }, + "EmbeddingModelUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "requester_config": { + "type": "object" + }, + "api_keys": { + "type": "array", + "items": { + "type": "object" + } + }, + "extra_args": { + "type": "object" + } + } + }, + "Bot": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "adapter": { + "type": "string", + "example": "telegram" + }, + "config": { + "type": "object" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "BotCreate": { + "type": "object", + "required": [ + "name", + "adapter", + "config" + ], + "properties": { + "name": { + "type": "string" + }, + "adapter": { + "type": "string" + }, + "config": { + "type": "object" + } + } + }, + "BotUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "config": { + "type": "object" + } + } + }, + "Pipeline": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "config": { + "type": "object" + }, + "is_default": { + "type": "boolean" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "PipelineCreate": { + "type": "object", + "required": [ + "name", + "config" + ], + "properties": { + "name": { + "type": "string" + }, + "config": { + "type": "object" + } + } + }, + "PipelineUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "config": { + "type": "object" + } + } + }, + "SuccessResponse": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "nullable": true + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "Error message" + } + } + } + }, + "responses": { + "UnauthorizedError": { + "description": "Authentication required or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "no_auth": { + "value": { + "code": -1, + "msg": "No valid authentication provided (user token or API key required)" + } + }, + "invalid_key": { + "value": { + "code": -1, + "msg": "Invalid API key" + } + } + } + } + } + }, + "NotFoundError": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "code": -1, + "msg": "Resource not found" + } + } + } + }, + "InternalServerError": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "code": -2, + "msg": "Internal server error" + } + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/en/index.md b/docs/en/index.md index 8c7b3173f..0613a5da9 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -1,3 +1,3 @@ diff --git a/docs/ja/deploy/command.md b/docs/ja/deploy/command.md new file mode 100644 index 000000000..24a9006f7 --- /dev/null +++ b/docs/ja/deploy/command.md @@ -0,0 +1,5 @@ +# コマンド + +LangBotは`!`で始まるメッセージをコマンドとして認識します。公式では[`EssentialCommands`プラグイン](https://space.langbot.app/market?author=langbot-team&plugin=EssentialCommands)を提供しており、よく使用されるコマンドが含まれています。 + +独自のコマンドプラグインを開発することもできます。詳細は[コマンドプラグイン開発](/en/plugin/dev/components/command.md)を参照してください。 diff --git a/docs/ja/deploy/knowledge/readme.md b/docs/ja/deploy/knowledge/readme.md new file mode 100644 index 000000000..83959dc4d --- /dev/null +++ b/docs/ja/deploy/knowledge/readme.md @@ -0,0 +1,34 @@ +# ナレッジベースの使用 + +LangBotはRAG(Retrieval-Augmented Generation)をネイティブサポートしています。組み込みナレッジベースを作成してパイプラインにバインドすることで、ナレッジベースの内容に基づいて質問に答えることができます。LangBotは外部のナレッジ検索サービス(例: Dify、RAGFlow)への接続もサポートしています。 + +## 組み込みナレッジベースの構築 + +:::info +- 組み込みナレッジベースの作成と使用には、まず埋め込みモデルの設定が必要です。[モデルの設定](/en/deploy/models/readme)をお読みください。 +::: + +ナレッジベースページで`ナレッジベースを作成`ボタンをクリックし、名前を入力し、既に設定済みの埋め込みモデルを選択してから`作成`をクリックします。 +作成後、ナレッジベースの「ドキュメント」タブに移動してドキュメントをアップロードします。LangBotはバックグラウンドで自動的に解析とインデックス化を行います。 + +create_kb + +## 外部ナレッジベースの接続 + +ナレッジベースページで「外部ナレッジベース」タブに切り替え、外部リトリーバーを追加します。ダイアログで使用するナレッジリトリーバープラグインを選択します(関連プラグインをプラグイン管理で事前にインストールしてください)。サポートされているリトリーバーは[プラグインマーケットプレイス](https://space.langbot.app/market?category=KnowledgeRetriever)で確認できます。 + +## ナレッジベースの使用 + +パイプライン設定に移動し、「AI」タブで`Local Agent`をランナーとして選択してから、先ほど作成したナレッジベースを選択します。 + +use_kb + +use_kb + +:::info +LangBotの組み込みナレッジベースは、ランナーが`Local Agent`に設定されている場合にのみ使用できます。他のランナーについては、それぞれのドキュメントを参照してください。 +::: + +これで`チャットデバッグ`でナレッジベースを使用したり、このパイプラインにリンクされたボットを通じて使用できます: + +use_kb_in_chat diff --git a/docs/ja/deploy/langbot/docker.md b/docs/ja/deploy/langbot/docker.md new file mode 100644 index 000000000..52f51b991 --- /dev/null +++ b/docs/ja/deploy/langbot/docker.md @@ -0,0 +1,33 @@ +# Dockerデプロイ + +:::warning +まず以下について学習することをお勧めします: + + - `Docker`と`Docker Compose`の使用方法 + - Dockerコンテナネットワーク通信の設定方法 +::: + +:::info +- Git、Docker、Docker Composeがインストールされていることを確認してください +::: + +プロジェクトをクローンします: + +```bash +git clone https://github.com/langbot-app/LangBot +cd LangBot/docker +``` + +コンテナを起動します: + +```bash +docker compose up +``` + +コンテナはWebUIアクセス用にポート`5300`をマッピングします。`http://127.0.0.1:5300`にアクセスしてWebUIを表示できます。 +また、メッセージプラットフォームアダプター用に予約されたポート`2280-2290`もマッピングします。 + +LangBotのデプロイ完了後、引き続き以下をお読みください: + +- [ボット設定ドキュメント](/en/deploy/platforms/readme) +- [モデル設定ドキュメント](/en/deploy/models/readme) diff --git a/docs/ja/deploy/langbot/manual.md b/docs/ja/deploy/langbot/manual.md new file mode 100644 index 000000000..e523a5733 --- /dev/null +++ b/docs/ja/deploy/langbot/manual.md @@ -0,0 +1,46 @@ +# 手動デプロイ + +:::warning +1. Python 3.10.1以上(3.10.0は除く)を使用してください。3.10.14を推奨します。Pythonがインストールされていない場合はインストールが必要です。 +2. この方法は推奨されません。手動デプロイは将来サポートされなくなる可能性があります。Dockerデプロイの使用を検討してください。 +::: + +## メインプログラムのインストール + +1. [リリース](https://github.com/langbot-app/LangBot/releases)ページにアクセスし、最新バージョンのzipパッケージ(推奨)`langbot-xxx-all.zip`をダウンロードします(Source Codeはダウンロードしないでください。WebUIが含まれていません)。展開して、展開されたディレクトリでコマンドライン(ターミナル)を開きます。 + +![リリースのダウンロード](/assets/image/zh/deploy/langbot/manual/dl_release.png) + +2. 依存関係のインストール + +依存関係の管理には[uv](https://docs.astral.sh/uv/)を使用します。 + +```bash +pip install uv +uv sync +``` + +3. メインプログラムを一度実行して設定ファイルを生成します + +```bash +uv run main.py +``` + +以下のメッセージが表示されます: + +``` + _ ___ _ +| | __ _ _ _ __ _| _ ) ___| |_ +| |__/ _` | ' \/ _` | _ \/ _ \ _| +|____\__,_|_||_\__, |___/\___/\__| + |___/ + +⭐️オープンソース: https://github.com/langbot-app/LangBot +📖ドキュメント: https://docs.langbot.app + +以下のファイルが存在しないため、自動的に生成されました。必要に応じて設定ファイルを変更して再起動してください: +- data/config.yaml +... +``` + +Ctrl+Cでプログラムを終了し、[ボットのデプロイ](/en/deploy/platforms/readme)ページに進んでください。 diff --git a/docs/ja/deploy/langbot/one-click/1panel.md b/docs/ja/deploy/langbot/one-click/1panel.md new file mode 100644 index 000000000..8532a5516 --- /dev/null +++ b/docs/ja/deploy/langbot/one-click/1panel.md @@ -0,0 +1,55 @@ +# 1Panelデプロイ + +[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)を使用してLangBotをワンクリックでデプロイします。 + +:::warning + +追加のコンテナを必要としないメッセージプラットフォーム(DiscordやLarkなど)を使用する予定がない場合、または1Panel上のDockerコンテナ間のネットワーク接続に精通していない場合は、1Panelのワンクリックデプロイは推奨されません。代わりに[Dockerデプロイ](/en/deploy/langbot/docker)の使用を検討してください。 + +::: + +:::info + +[Alibaba Cloud](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)なら、年間38元という低価格でサーバーを入手でき、さらに20%の割引も受けられます。1Panelをワンクリックでインストールするのがより便利です。 + +::: + +## 1Panelのインストール + +> 推奨サーバーシステム(1Panelより): Debian 12、Ubuntu 22など + +この記事では、サーバーにデフォルトでパブリックIPv4アドレスがあることを前提としています。パブリックIPのないホームマシンを使用している場合は、以下で説明する内部ネットワーク経由で関連ページにアクセスできます。 + +[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)にアクセスし、1Panelが公式に提供するLinuxパネルインストールスクリプトを使用します。お使いのオペレーティングシステムに応じて対応するスクリプトを選択してください。 + +![1Panelのインストール](/assets/image/zh/deploy/langbot/one-click/1p_install_01.png) + +対応するスクリプトをコピーし、サーバーに貼り付けて実行します。 + +しばらく待つと、1Panelのインストールが完了します。 + +次に`外部アドレス`をコピーしてブラウザで開きます。 + +## LangBotのインストール + +`アプリストア`を開き、`AI`カテゴリを選択し、LangBotをクリックしてインストールします。 + +![LangBotのインストール](/assets/image/zh/deploy/langbot/one-click/1p_langbot_01.png) + +`外部ポートアクセス`のチェックボックスをオンにして、確認をクリックします。 + +![LangBotのインストール](/assets/image/zh/deploy/langbot/one-click/1p_langbot_02.png) + +しばらく待つと、インストールが完了します。 + +左側の`コンテナ`をクリックし、`コンテナ`カテゴリを選択すると、LangBotコンテナバーが表示されます。 + +![LangBotコンテナ情報の表示](/assets/image/zh/deploy/langbot/one-click/1p_langbot_03.png) + +サーバーのパブリックIPアドレスをコピーします。例: `http://xxx.xxx.xxx.xxx:5300`(xxx.xxx.xxx.xxxは1Panelが配置されているサーバーのIPアドレス、5300はポート番号)。 + +アドレスを開き、管理者のメールアドレスとパスワードを入力して、初期化をクリックします。 + +その後、ビジュアルインターフェースでLangBotを設定できます。 + +次に、[メッセージプラットフォームのデプロイ](/en/deploy/platforms/readme)ページを引き続きお読みください。 diff --git a/docs/ja/deploy/langbot/one-click/bt.md b/docs/ja/deploy/langbot/one-click/bt.md new file mode 100644 index 000000000..5deb3bf63 --- /dev/null +++ b/docs/ja/deploy/langbot/one-click/bt.md @@ -0,0 +1,53 @@ +# aaPanelデプロイ + +[aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot)を使用してLangBotをワンクリックでデプロイします。 + +:::warning +- 追加のコンテナを必要としないDiscordやFeishuなどのメッセージプラットフォームを使用する予定がない場合、またはaaPanel上のDockerコンテナネットワーキングに精通していない場合は、aaPanelでのワンクリックデプロイは推奨されません。[Dockerデプロイ](/en/deploy/langbot/docker)の使用を検討してください。 +- 既にaaPanelがインストールされている場合は、バージョン**9.2.0**以上に更新してください +::: + + +## aaPanelのインストール + +> 推奨サーバーシステム(aaPanelより): Debian 12、Ubuntu 22など +> +> このドキュメントでは、パブリックIPv4アドレスを持つサーバーがあることを前提としています。パブリックIPのないホームマシンを使用している場合は、以下で言及する内部ネットワーク経由で関連ページにアクセスできます。 + +[aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot)を開き、aaPanel公式が提供するLinuxパネルインストールスクリプトを使用し、お使いのシステムに基づいて対応するスクリプトを選択します。 + +![aaPanelのインストール](/assets/image/zh/deploy/langbot/one-click/bt_install_01.png) + +対応するスクリプトをコピーしてサーバーに貼り付けて実行します。 + +## LangBotのインストール + +しばらく待つと、aaPanelのインストールが完了します。 + +このようなメッセージが表示されますので、外部パネルアドレスをコピーしてブラウザで開きます。 + +![aaPanelアクセスアドレス](/assets/image/zh/deploy/langbot/one-click/bt_install_02.png) + +初めて開くと、`推奨インストールスイート`のポップアップが表示されます。閉じてスキップできます。 + +次にサイドバーの`docker`をクリックします。初めての場合、DockerとDocker Composeサービスのインストールを求められます。プロンプトが表示されたら「今すぐインストール」をクリックするか、既にインストールされている場合は無視してください。 + +次に`Docker -> アプリストア`に移動し、`LangBot`を検索し(大文字小文字に注意)、`インストール`をクリックし、デフォルト設定を使用します。 + +少し待つと、`langbot_XXXX`という名前のコンテナが`実行中`として表示されます。 + +![LangBotコンテナの作成](/assets/image/zh/deploy/langbot/one-click/bt_langbot_01.png) + +上の画像の赤い円をクリックして実行ログを表示します。 + +![LangBotコンテナログの表示](/assets/image/zh/deploy/langbot/one-click/bt_langbot_02.png) + +WebUI設定ページ(ビジュアル設定ページ)の外部および内部アクセスパスが表示されます。パブリックアドレスをコピーします。例: `http://xxx.xxx.xxx.xxx:5300`(xxx.xxx.xxx.xxxはaaPanelのIP、5300はポート番号で、画像に示されているように異なる場合があります)。 + +開いた後、管理者のメールアドレスとパスワードを入力し、初期化をクリックします。 + +その後、ビジュアルインターフェースで設定を進めることができます。 + +JSON設定ファイルを直接変更したい場合は、上の画像に示されているローカルマッピングディレクトリを参照できます。インストールディレクトリに移動すると、`data`フォルダは設定ファイルの保存に使用され、`plugins`フォルダはプラグイン関連ファイルに使用されます。 + +次に、[メッセージプラットフォームのデプロイ](/en/deploy/platforms/readme)ページを引き続きお読みください。 diff --git a/docs/ja/deploy/langbot/package.md b/docs/ja/deploy/langbot/package.md new file mode 100644 index 000000000..30ed0413e --- /dev/null +++ b/docs/ja/deploy/langbot/package.md @@ -0,0 +1,13 @@ +# パッケージマネージャーでのデプロイ + +:::info +Windows、Linux、Mac OSなどをサポート。テスト環境および個人使用シナリオに推奨。本番レベルの環境では[Dockerデプロイ](/en/deploy/langbot/docker.html)を使用してください。 +::: + +LangBotはパッケージ化されてPyPIにリリースされています。[uv](https://docs.astral.sh/uv/getting-started/installation/)をインストールしてから、空のディレクトリで以下のコマンドを実行してください: + +```bash +uvx langbot@latest +``` + +これにより現在のディレクトリが作業ディレクトリとして設定され、`http://localhost:5300`にアクセスして使用を開始できます。 diff --git a/docs/ja/deploy/mcp/readme.md b/docs/ja/deploy/mcp/readme.md new file mode 100644 index 000000000..ac08378e6 --- /dev/null +++ b/docs/ja/deploy/mcp/readme.md @@ -0,0 +1,37 @@ +# MCPサーバーの使用 + + +LangBotはSSEモードのMCPサーバーをサポートしています。MCPサーバーを追加して、大規模言語モデルのツール呼び出し機能を活用し、LLMリクエストをより適切に処理できます。 + +:::info +MCPサービスはSSEモードのみをサポートしています。 +- MCPサーバーの推奨取得チャネル: [Composio MCP](https://mcp.composio.dev/) +::: + +## モデルのFunction Callingを有効化 + +画像に示すように、モデルの`Function Calling`機能を有効にします。 + +enable function call + +## MCPサーバーの作成 + +`プラグイン管理`をクリックしてから`MCP管理`をクリックします: + +server page + +右上の`追加`をクリックしてから`MCPサーバーを作成`をクリックします。 + +create new mcp server + +例えば、Fetch HTMLサーバーを使用するには、対応するURLを入力し、`テスト`をクリックしてMCPサーバーをテストし、`送信`をクリックしてサーバーを追加します。 + +追加後、カードのスイッチをクリックしてMCPサーバーに接続します。カードをクリックしてMCPサーバーの詳細を表示します: + +detailed server + +## 効果 + +パイプライン設定で`Local Agent`をランナーとして選択し、function callingをサポートするモデルを使用する必要があります。 + +dialog with mcp diff --git a/docs/ja/deploy/models/readme.md b/docs/ja/deploy/models/readme.md new file mode 100644 index 000000000..f16311d39 --- /dev/null +++ b/docs/ja/deploy/models/readme.md @@ -0,0 +1,31 @@ +# モデルの設定(Models) + +モデルはパイプラインによってメッセージ処理に使用されます。最初に設定したモデルがデフォルトパイプラインのモデルとして設定されます。 + +![arch](/assets/image/zh/deploy/models/arch.png) + +複数のモデルを追加して、パイプラインでどのモデルを使用するかを選択できます。 + +![モデル設定](/assets/image/zh/deploy/models/model_config.png) + +これら4つのパラメータを入力します: `モデル名`、`モデルプロバイダー`、`リクエストURL`、`APIキー`、そして送信します。 + +モデルの機能については、特定のモデルの特性に応じて選択してください: + +- ビジュアル機能: 画像を認識するために有効にする必要があります + +- Function Calling: 会話でAgentツールを使用するために有効にする必要があります + +:::info + +*APIキーをお持ちでない場合は、[このリレーステーションから入手できます](https://api.qhaigc.net/)* + +サードパーティのAPIリレーや他のモデルプロバイダーを使用する必要がある場合、 + +`OpenAI`を選択してください + +リクエストURLにリレーのBase URLを入力します。例: + +![モデル設定](/assets/image/zh/deploy/models/other_provider.png) + +::: diff --git a/docs/ja/deploy/pipelines/coze.md b/docs/ja/deploy/pipelines/coze.md new file mode 100644 index 000000000..cc976ef15 --- /dev/null +++ b/docs/ja/deploy/pipelines/coze.md @@ -0,0 +1,49 @@ +# Coze APIの統合 + +このドキュメントでは、CozeプラットフォームからTokenとBot IDを取得し、LangBotパイプライン設定に入力する方法を説明します。 + +## 1. TokenとBot IDの取得 + +1. Cozeプラットフォームにログインし、開発者コンソールに入ります。 +![Coze Application API Key](/assets/image/zh/deploy/pipelines/coze/coze07.png) + +2. 「API管理」でトークンを作成してコピーします。 +![Coze Application API Key](/assets/image/zh/deploy/pipelines/coze/coze06.png) + +:::info +Coze認証では、coze.cnは「サービスIDと認証情報」を通じた長期認証をサポートしていますが、coze.comはPersonal Access Tokenのみを提供しています。 +::: + +3. プロジェクト開発セクションから自分のエージェントを選択します(または新しいエージェントを作成します)。取得したIDが`bot_id`です。 +![Coze bot_id](/assets/image/zh/deploy/pipelines/coze/coze05.png) + +* エージェントを公開する際は、必ずAPIオプションを選択してください +![Coze Application API Key](/assets/image/zh/deploy/pipelines/coze/coze04.png) + +以下の2つの情報を安全に保管してください: +- **token**: Cozeプラットフォームで生成されたトークン +- **bot_id**: Bot ID + +## 2. LangBotでの設定入力 + +1. LangBot WebUIを開き、パイプラインの設定ページに移動します(または新しいパイプラインを作成してその設定ページに入ります) + +2. 「AI機能」で、ランナーとして`Coze API`を選択します + +3. ランナーの設定項目に入力します: + - **token**: CozeプラットフォームからコピーしたAPIトークンを貼り付けます + - **bot_id**: 対応するBot IDを貼り付けます + - 使用しているCozeサイトに応じて`API Base URL`を選択してください: coze.cnの場合は`https://api.coze.cn`を入力してください; coze.comの場合は`https://api.coze.com`を入力してください + + ![パイプライン設定](/assets/image/zh/deploy/pipelines/coze/coze08.png) + +4. 「保存」をクリックして設定を完了します + +完了すると、このパイプライン内でCozeエージェントを呼び出して対話処理ができます + +## よくある質問(FAQ) + +- **保存が失敗するか、呼び出しがエラーを返す**: トークンとbot_idが正しく、余分なスペースが含まれていないことを確認してください +- **`Coze API`を選択できない**: 現在のバージョンがこのランナーをサポートしているか確認してください。まだサポートされていない場合は、Cozeランナーを含むバージョンにアップグレードしてください + +一般的なパイプライン設定の詳細については、[対話パイプライン設定の変更](/en/deploy/pipelines/readme)を参照してください diff --git a/docs/ja/deploy/pipelines/dify.md b/docs/ja/deploy/pipelines/dify.md new file mode 100644 index 000000000..bc006c13a --- /dev/null +++ b/docs/ja/deploy/pipelines/dify.md @@ -0,0 +1,42 @@ +# LangBotでのDifyの使用 + +[Dify](https://dify.ai)は、オープンソースの大規模言語モデル(LLM)アプリケーション開発プラットフォームです。Backend as ServiceとLLMOpsの概念を組み合わせ、開発者が本番グレードの生成AIアプリケーションを迅速に構築できるようにします。 +Difyは、チャットアシスタント(Chatflowを含む)、エージェント、テキスト生成アプリケーション、ワークフローなどのタイプのアプリケーションを作成できます。 + +LangBotは現在、3種類のDifyアプリケーションをサポートしています: `チャットアシスタント`(Chatflowを含む)、`エージェント`、`ワークフロー`。 + +## Difyでのアプリケーション作成 + +[Difyドキュメント](https://docs.dify.ai)に従ってDifyをデプロイし、アプリケーションを作成してください。 + +アプリケーションを公開した後、アプリケーションの`Access API`ページに移動してAPIキーを生成します。 + +![Dify Application API Key](/assets/image/zh/deploy/pipelines/dify/dify_sv_api_01.png) + +LangBotのパイプライン`AI機能`を設定するために、APIサーバーとAPIキーを保存します。 + +:::info +上記はDifyクラウドサービスバージョンの例です。セルフホストコミュニティバージョンを使用している場合は、LangBotの`base-url`として独自のDifyサービスアドレスを使用し、パスとして`/v1`を追加してください。 + +- LangBotとDifyが同じホストにデプロイされており、両方ともDockerを使用してデプロイされている場合は、記事[ネットワーク設定の詳細](/zh/workshop/network-details.html#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD)を参照してください。この場合、Difyを起動するdocker-compose.yamlファイル内のすべてのコンテナの`networks`に`langbot-network`を追加し、`nginx`コンテナにコンテナ名`dify-nginx`を追加し、最後にLangBot設定で`base-url`を`http://dify-nginx/v1`に設定します。 +- その他のケースについては、会社の運用チームにお問い合わせください。 +::: + +## LangBotの設定 + +LangBot WebUIページを開き、新しいパイプラインを追加するか、既存のパイプラインのAI機能設定ページに切り替えます。 + +![設定開発項目](/assets/image/zh/deploy/pipelines/dify/dify_sv_api_02.png) + +::: info +### ワークフロー出力キー + +Difyワークフローアプリケーションを使用している場合は、出力コンテンツを渡すキーとして`summary`を使用してください。 + +![Difyワークフローアプリケーション出力キー](/assets/image/zh/deploy/pipelines/dify/dify_workflow_output_key.png) + +## 出力処理 + +ワークフローアプリケーションまたはエージェントアプリケーションを使用している場合、LangBotのパイプライン`出力処理`で`track-function-calls`を有効にすると、Difyが各ツール呼び出しを実行する際に`calling function xxx`というメッセージがユーザーに出力されます。 +ただし、`chat`アプリケーション(チャットアシスタント -> ワークフローオーケストレーション)の下で`ChatFlow`を使用している場合は、設定に関係なく、Answer(直接返信)ノードによって返されるテキストのみが出力されます。 +::: diff --git a/docs/ja/deploy/pipelines/langflow.md b/docs/ja/deploy/pipelines/langflow.md new file mode 100644 index 000000000..521a0f542 --- /dev/null +++ b/docs/ja/deploy/pipelines/langflow.md @@ -0,0 +1,31 @@ +# LangBotでのLangflowの使用 + +[Langflow](https://langflow.com/)は、AIベースのエージェントとワークフローを構築およびデプロイするためのオープンソースプロジェクトです。ローカルおよびクラウドデプロイをサポートし、他のアプリケーションが統合できるAPIを提供します。 + +LangBotは現在、ランナーとしてLangflowの使用をサポートしています。 + +## Langflowでのワークフロー作成 + +[Langflowドキュメント](https://langflow.com/docs/introduction)に従ってLangflowインスタンスをデプロイしてください。 + +デフォルトテンプレートのSimple Agentの例: + +![create_flow](/assets/image/zh/deploy/pipelines/langflow/create_flow.png) + +必要に応じてワークフローを変更できます: + +![edit_flow](/assets/image/zh/deploy/pipelines/langflow/edit_flow.png) + +## LangBotの設定 + +LangBot WebUIページを開き、新しいパイプラインを追加するか、既存のパイプラインのAI機能設定ページに切り替え、ランナーとして`Langflow API`を選択します。 + +![set_langflow_runner](/assets/image/zh/deploy/pipelines/langflow/set_langflow_runner.png) + +プロンプトに従って他の設定を入力します。`Base URL`(実際のネットワーク状況に応じて入力)、`API Key`、`Flow ID`などが含まれます。API KeyはLangflowの設定から取得できます: + +![get_api_key](/assets/image/zh/deploy/pipelines/langflow/get_api_key.png) + +Flow IDは、編集ページの右上にある`共有` -> `APIアクセス`ボタンをクリックし、サンプルコードから取得できます: + +![get_flow_id](/assets/image/zh/deploy/pipelines/langflow/get_flow_id.png) diff --git a/docs/ja/deploy/pipelines/n8n.md b/docs/ja/deploy/pipelines/n8n.md new file mode 100644 index 000000000..41d981034 --- /dev/null +++ b/docs/ja/deploy/pipelines/n8n.md @@ -0,0 +1,49 @@ +# LangBotでのn8nの使用 + +[n8n](https://n8n.io/)は、さまざまな自動化タスクを作成、スケジュール、実行できるオープンソースのワークフロー自動化プラットフォームです。 + +LangBotは現在、n8nワークフローの`Webhook`ノードを通じてワークフローをトリガーし、レスポンスを受信することをサポートしています。 + +## ランナーとしてのn8nの使用 + +既存のパイプラインの設定ページを開くか、新しいパイプライン(推奨)を作成して設定ページを開いてください。`AI`で`n8n Workflow API`をランナーとして選択します。 + +![ランナーとしてのn8n](/assets/image/zh/deploy/pipelines/n8n/config_runner.png) + +次に、以下の内容に従って他の設定を構成して入力します。 + +## n8nワークフロー接続の設定 + +![n8nワークフロー](/assets/image/zh/deploy/pipelines/n8n/create_wf.png) +または +![n8nワークフロー](/assets/image/zh/deploy/pipelines/n8n/create_wf01.png) + +トリガーとして`Webhook`または`On chat message`を選択し、以下のように設定します: +- Webhook: + ![n8n webhook設定](/assets/image/zh/deploy/pipelines/n8n/config_webhook.png) +- On chat message: + ![n8n on chat message設定](/assets/image/zh/deploy/pipelines/n8n/config_n8n_onchatmessage.png) + +:::info +ストリーミングレスポンスが必要な場合は、`Response Mode`を`Streaming`に設定します。 +![n8nストリーミング設定](/assets/image/zh/deploy/pipelines/n8n/config_response_model.png) +::: + +:::info +認証は、LangBotのパイプライン設定の認証方法に対応しており、必要に応じて変更できます。 + +![n8nワークフロー設定](/assets/image/zh/deploy/pipelines/n8n/config_auth.png) +::: + +AIモデルを呼び出すノードを`AI Agent`として設定し、以下のセットアップに従います: +> ストリーミングレスポンスの場合、赤い枠で強調表示されている項目を追加します。ストリーミングが不要な場合は、このステップをスキップできます。 + +![n8n AIモデル呼び出し設定](/assets/image/zh/deploy/pipelines/n8n/config_call_ai.png) + +n8nのワークフローレスポンスコンテンツについては、`Respond to Webhook`ノードを使用し、以下の画像に従って設定してください(`AI Agent`ノードでストリーミングレスポンスを選択した場合、このステップは不要です): + +![n8nワークフローレスポンス設定](/assets/image/zh/deploy/pipelines/n8n/config_respond.png) + +`Response Body`のレスポンスコンテンツキー名は、LangBotのパイプライン設定の`出力キー名`と一致する必要があります。 + +n8nワークフロー設定の完了後、上部の`Active`をクリックしてワークフローを有効にしてください。 diff --git a/docs/ja/deploy/pipelines/readme.md b/docs/ja/deploy/pipelines/readme.md new file mode 100644 index 000000000..2d302631a --- /dev/null +++ b/docs/ja/deploy/pipelines/readme.md @@ -0,0 +1,53 @@ +# 対話パイプライン設定の変更(Pipelines) + +パイプラインは、メッセージを受信した後の処理フローと、大規模言語モデルとの情報交換を制御します。各ボットは1つのパイプラインにバインドでき、同じパイプラインは複数のボットにバインドできます。 + +LangBotは最初の起動時にデフォルトパイプラインを自動的に作成します。ボットを作成すると、自動的にデフォルトパイプラインにバインドされます。最初のモデルを作成すると、自動的にデフォルトパイプラインのモデルとして設定されます。 + +![arch](/assets/image/zh/deploy/pipelines/arch.png) + +異なるシナリオに適応するために、異なるボット用に複数のパイプラインを作成できます。 + + + +現在、パイプラインでは以下の機能を設定できます: + +## AI機能 + +以下を選択して使用できます: `組み込みエージェント`、[`Dify`](https://dify.ai/)、[`n8n`](https://n8n.io/) + +AI機能は主に2つの部分に分かれています: ランナーの選択とランナーパラメータの設定。 + +ランナーは、メッセージを処理するために大規模モデルをスケジュールする方法を定義します。デフォルトは`組み込みエージェント`で、これはLangBotによって実装された複数ラウンドのエージェント戦略です。このランナーが選択されている場合のみ、LangBot内で設定されたモデルとツールが使用されます。 + +** + +edit_pipeline + +`Dify`、[`n8n`](https://n8n.io/)などの外部LLMOpsプラットフォームを使用することもできます。この場合、使用されるモデル、プロンプト、ツール、その他のリソースはLLMOpsプラットフォームによって提供されます。 + +more_runner + +- Difyへの接続の詳細手順は、[チュートリアルを参照](/en/deploy/pipelines/dify.html)してください。 +- n8nへの接続の詳細手順は、[チュートリアルを参照](/en/deploy/pipelines/n8n.html)してください。 + +### 会話変数 +外部LLMOpsプラットフォームを使用する場合、LangBotは以下のパラメータを明示的に渡します。これらをLLMOpsプラットフォームワークフローの開始ノードに追加できます(以下の画像はDifyの例です): + +- `launcher_type`: ランチャーオブジェクトタイプ、プライベートチャットの場合は`person`、グループチャットの場合は`group` +- `launcher_id`: ランチャーオブジェクトID、プライベートチャットの場合はユーザーID、グループチャットの場合はグループID +- `sender_id`: 送信者ID +- `user_message_text`: ユーザーメッセージのプレーンテキスト +- `session_id`: ユーザーセッションID、プライベートチャットの場合は`person_`、グループチャットの場合は`group_` +- `conversation_id`: 文字列、ユーザーセッションID、LangBotによって生成されます。ユーザーがセッションをリセットした後に再生成されます +- `msg_create_time`: 数値型、このメッセージが受信されたタイムスタンプ(秒) +- `group_name`: グループ名、グループメッセージを受信した場合のみ設定されます +- `sender_name`: 送信者名 + +[プラグインを通じて任意の変数をカスタマイズできます](/en/plugin/dev/apis/common.html#set-request-variables)。 + +![Difyワークフロー開始ノード設定](/assets/image/zh/workshop/dify-service-api/dify_workflow_var.png) + +## その他の設定 + +設定フォームの説明を参照してください。 diff --git a/docs/ja/deploy/platforms/dingtalk.md b/docs/ja/deploy/platforms/dingtalk.md new file mode 100644 index 000000000..8dcee19fd --- /dev/null +++ b/docs/ja/deploy/platforms/dingtalk.md @@ -0,0 +1,78 @@ +# DingTalk ボットのデプロイ + +DingTalk に LangBot をデプロイします。 + +## ボットの作成 + +[DingTalk 開発者バックエンド](https://open-dev.dingtalk.com/?spm=ding_open_doc.document.0.0.74f445e5MkawbT#/)にアクセスし、ログインして組織に入ります。ログインに成功したら、オープンプラットフォームに入ります。以下のように表示されます： +![DingTalk Open Platform](/assets/image/zh/deploy/bots/dingtalk/dingtalk1.png) + +上部の「アプリケーション開発」をクリックし、右側の青いボタン「アプリケーションを作成」をクリックして、ボットの基本情報を入力し、保存をクリックします。 + +ボットのバックエンドに入ります。例えば、langbot2 という名前のボットがある場合、管理ページは以下のように表示されます： +![Bot Page](/assets/image/zh/deploy/bots/dingtalk/dingtalk2.png) + +## ボットの設定 + +「アプリケーション機能を追加」、「その他のアプリケーション機能」、「ロボット」の「設定」をクリックし、設定をクリックして情報を入力します。以下のように： +![Bot Configuration](/assets/image/zh/deploy/bots/dingtalk/dingtalk3.png) + +ページ下部の「公開」をクリックし、公開が成功したら、ボットページの左下にある「バージョン管理と公開」をクリックします。以下のように： +![Version Management and Publishing](/assets/image/zh/deploy/bots/dingtalk/dingtalk4.png) + +初めてボットを作成する場合、右側は空なので、「新しいバージョンを作成」をクリックし、その中で情報を設定し、「アプリケーションの表示範囲」を設定して、保存をクリックします。 + +「イベントサブスクリプション」をクリックし、プッシュ方式を「ストリームモードプッシュ」に変更します。 + +カードストリーミングが必要な場合は、権限管理でカード権限を申請する必要があります。以下のように： +![Before applying for card permissions](/assets/image/zh/deploy/bots/dingtalk/dingtalk6.png) + +![After applying for card permissions](/assets/image/zh/deploy/bots/dingtalk/dingtalk7.png) + +さらに、カードメッセージの場合、主にカードテンプレートを作成し、テンプレート ID を記録して設定に入力する必要があります。手順は以下の通りです： +> カードコンテンツテンプレート ID は、開発者バックエンドにログイン > [カードプラットフォーム](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)から取得できます + +新しいテンプレートを作成する際に情報を入力します。以下のように： +![Fill in information for new template](/assets/image/zh/deploy/bots/dingtalk/dingtalk8.png) + +プリセットテンプレートを選択します（最初のものを選択し、後でテンプレートの内容を変更します）。以下のように： +![Select preset template](/assets/image/zh/deploy/bots/dingtalk/dingtalk9.png) +使用をクリック +![Click](/assets/image/zh/deploy/bots/dingtalk/dingtalk10.png) +作成 +![Create](/assets/image/zh/deploy/bots/dingtalk/dingtalk11.png) + +作成をクリックすると、テンプレートの編集にリダイレクトされます。以下のように、希望するカードメッセージを自由に編集できます： +![Edit template](/assets/image/zh/deploy/bots/dingtalk/dingtalk12.png) + +メインコンテンツについては、デフォルトの「content」をそのままにしておきます： +![Don't modify](../../../assets/image/zh/deploy/bots/dingtalk/dingtalk13.png) + +編集を終え、すべて正しいことを確認したら、保存してテンプレート ID をコピーし、設定ファイルに入力します： +![Save](../../../assets/image/zh/deploy/bots/dingtalk/dingtalk14.png) +![Copy template ID](../../../assets/image/zh/deploy/bots/dingtalk/dingtalk15.png) + +## 設定情報の入力 + +「認証情報と基本情報」をクリックし、「Client ID」と「Client Secret」を記録します。 +「アプリケーション機能」、「ロボット」をクリックし、RobotCode とロボット名を記録します。 +`markdown_card` は Markdown 形式の返信を有効にするかどうかです。 +上記の設定項目を記録し、LangBot ボット設定フォームに入力します + +[カードプラットフォーム](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)をクリックし、テンプレートリストから対応するバインドされたテンプレート ID をコピーし、カードテンプレート ID フィールドに入力します。 + +![Connect to LangBot](/assets/image/zh/deploy/bots/dingtalk/connect_to_langbot.png) + +ストリーミング関連： +![img.png](../../../assets/image/zh/deploy/bots/lark/lark_15.png) + +**LangBot を起動します**。 + +## ボットの追加 + +この記事では DingTalk Windows デスクトップ版を例として使用します。上部の「検索」、「機能」をクリックし、先ほど作成したボットの名前を入力します。以下のように： +![robot_png](/assets/image/zh/deploy/bots/dingtalk/dingtalk5.png) + +ボットをクリックしてチャットします。 + +グループに追加したい場合は、DingTalk グループの「グループ管理」、「ロボット」、「ロボットを追加」をクリックし、ボット名を検索してグループで使用します。 diff --git a/docs/ja/deploy/platforms/discord.md b/docs/ja/deploy/platforms/discord.md new file mode 100644 index 000000000..ef5a2094d --- /dev/null +++ b/docs/ja/deploy/platforms/discord.md @@ -0,0 +1,55 @@ +# Discord ボットに接続 + +## ボットの作成 + +[Discord Developer Portal](https://discord.com/developers/applications)にアクセスし、ログインしてアプリケーションを作成します。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_01.png) + +基本情報を変更し、「Save Changes」をクリックして保存します。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_02.png) + +左側の「Bot」をクリックし、「Reset Token」をクリックして、生成された Token をコピーします。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_03.png) + +そして、このページの「Privileged Gateway Intents」のすべてのオプションをチェックし、「Save Changes」をクリックして保存します。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_05.png) + +**最後に、左側の「OAuth2」をクリックし、ページの「Client ID」をコピーします。** + +## LangBot に接続 + +新しいボットを追加するためにクリックし、前の手順で取得した「Client ID」と「Token」を設定に入力します。 + +![alt text](/assets/image/zh/deploy/bots/discord/connect_to_langbot.png) + +:::warning + +中国本土内でこのアダプターを使用している場合、ネットワークプロキシを設定する必要がある場合があります。 + +::: + +入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: discord` と表示されます。LangBot を実行し続けてください。 + +## ボットをサーバーに招待 + +まずサーバーを作成し、次にボットをサーバーに招待する必要があります。 + +「OAuth2」ページに移動し、「URL Generator」を選択し、「bot」を選択して、画像に示されている権限をチェックします。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_06.png) + +![alt text](/assets/image/zh/deploy/bots/discord/discord_07.png) + +「Copy」をクリックし、生成された URL をブラウザに貼り付けて開き、ボットをサーバーに招待します。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_08.png) + +## ボットの使用 + +グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。 + +![alt text](/assets/image/zh/deploy/bots/discord/discord_09.png) diff --git a/docs/ja/deploy/platforms/kook.md b/docs/ja/deploy/platforms/kook.md new file mode 100644 index 000000000..2025fc0a9 --- /dev/null +++ b/docs/ja/deploy/platforms/kook.md @@ -0,0 +1,63 @@ +# KOOK ボットの統合 + +## ボットの作成 + +[KOOK Developer Center](https://developer.kookapp.cn/)にアクセスし、ログインしてコンソールにアクセスします。 + +![KOOK Developer Console](/assets/image/zh/deploy/bots/kook/01-dashboard.png) + +「アプリケーションを作成」をクリックし、アプリケーション情報を入力します。 + +![Create Application](/assets/image/zh/deploy/bots/kook/02-create-app.png) + +アプリケーションが作成されたら、アプリケーション詳細ページに入ります。 + +![Application Created](/assets/image/zh/deploy/bots/kook/03-app-created.png) + +アプリケーション概要ページでアプリケーションの基本情報を表示できます。 + +![Application Overview](/assets/image/zh/deploy/bots/kook/04-app-overview.png) + +## Bot Token の取得 + +アプリケーションページで、「Bot」タブをクリックし、Bot Token をコピーして安全に保存します。後で必要になります。 + +![Get Bot Token](/assets/image/zh/deploy/bots/kook/05-bot-token.png) + +## ボット権限の設定 + +**重要：**「Bot」設定で、「メッセージフィルタリング」オプションを見つけてクリックして設定します。 + +![Message Filter Settings](/assets/image/zh/deploy/bots/kook/07-message-filters.png) + +チャンネルメッセージやプライベートメッセージイベントを含む、すべてのメッセージ関連イベント権限を有効にします。そうしないと、ボットはメッセージを受信できません。 + +![Enable Permissions](/assets/image/zh/deploy/bots/kook/08-permissions-enabled.png) + +## ボットの招待 + +ボット設定ページで、招待リンクを生成してボットをサーバーに招待できます。 + +![Generate Invitation Link](/assets/image/zh/deploy/bots/kook/06-invite-link.png) + +## LangBot に接続 + +LangBot Webui ページを開き、「Bots」ページで新しいボットを作成するためにクリックします。 + +![LangBot Bot Management](/assets/image/zh/deploy/bots/kook/09-langbot-bots.png) + +KOOK プラットフォームを選択し、ボット名と Bot Token を入力します。 + +![Configure KOOK Bot](/assets/image/zh/deploy/bots/kook/10-bot-config.png) + +保存後、ボットがリストに表示されます。 + +![Bot Created](/assets/image/zh/deploy/bots/kook/11-bot-created.png) + +有効化ボタンをクリックしてボットを起動します。正常に設定されている場合、ボットのステータスは実行中として表示されます。 + +![Bot Enabled](/assets/image/zh/deploy/bots/kook/12-bot-enabled.png) + +## ボットの使用 + +KOOK サーバーで、ボットは正常にメッセージを受信して返信できるようになりました。ボットはチャンネルメッセージとプライベートメッセージの両方をサポートしています。 diff --git a/docs/ja/deploy/platforms/lark.md b/docs/ja/deploy/platforms/lark.md new file mode 100644 index 000000000..4d6a90996 --- /dev/null +++ b/docs/ja/deploy/platforms/lark.md @@ -0,0 +1,86 @@ +# Feishu ボットに接続 + +## ボットの作成 + +[Feishu Open Platform](https://open.feishu.cn/app)にアクセスし、ログインして、企業の自己構築アプリケーションまたはストアアプリケーションを作成します。[(違いの紹介)](https://open.feishu.cn/document/platform-overveiw/overview) + +![alt text](/assets/image/zh/deploy/bots/lark/lark_01.png) + +![alt text](/assets/image/zh/deploy/bots/lark/lark_02.png) + +アプリケーションにボット機能を追加します： +![alt text](/assets/image/zh/deploy/bots/lark/lark_03.png) + +権限管理で画像に示されている権限を追加します： + +![alt text](/assets/image/zh/deploy/bots/lark/lark_04.png) + +カードストリーミング権限が必要な場合は、画像に示されている次のカード作成と更新権限を追加します： + +![img_1.png](../../../assets/image/zh/deploy/bots/lark/lark_14.png) + +## LangBot に接続 + +「認証情報と基本情報」ページで `app_id` と `app_secret` を見つけます。 + +![alt text](/assets/image/zh/deploy/bots/lark/lark_05.png) + + + +LangBot の Webui 設定ページを開き、新しいボットを作成します + +フォームに関連情報を入力します + +![alt text](/assets/image/zh/deploy/bots/lark/connect_to_langbot.png) + +ストリーミング関連： +![Streaming related](../../../assets/image/zh/deploy/bots/lark/connect_to_langbot01.png) + +入力後、LangBot を起動します。設定が成功した場合、ログに `[01-29 23:42:56.796] manager.py (68) - [INFO] : Initializing platform adapter 1: lark` と表示されます。LangBot を実行し続けてください。 + +:::warning +デフォルトでは、WebSocket 長時間接続モードが使用されます。これは以下の長時間接続サブスクリプションに対応しています。ただし、場合によっては（国際版の Feishu など）、長時間接続モードが利用できない場合があります。その場合は、Webhook モードを使用する必要があります。これは、「開発者サーバーにイベントを送信」モードに対応しています。次の設定を参照してください： + +- `enable-webhook`：`true` に設定 +- `encrypt-key`：「イベントとコールバック」ページの「暗号化戦略」の「Encrypt Key」に設定 + +Webhook モードでは、LangBot をパブリック IP を持つサーバーにデプロイし、ファイアウォールが上記で設定したポートを開いていることを確認する必要があることに注意してください。 +::: + +## イベントサブスクリプションの設定 + +「イベントとコールバック」ページに移動し、サブスクリプション方式を「長時間接続」として設定します： + +![alt text](/assets/image/zh/deploy/bots/lark/lark_07.png) + +そして、イベント：「メッセージを受信」を追加します + +![alt text](/assets/image/zh/deploy/bots/lark/lark_08.png) + +:::warning +Webhook モード設定方法： + +![alt text](/assets/image/zh/deploy/bots/lark/lark_13.png) + +まず LangBot を起動してください。ここにサーバーアドレスとポートを入力します。パスは `/lark/callback` です。「保存」をクリックします。 + +::: + +## ボットの公開 + +上部の「バージョンを作成」をクリックし、バージョン番号とその他の情報を入力し、下部の「保存」をクリックします。 + +![alt text](/assets/image/zh/deploy/bots/lark/lark_09.png) + +ボットを Feishu グループに追加して使用します： + +![alt text](/assets/image/zh/deploy/bots/lark/lark_10.png) + +![alt text](/assets/image/zh/deploy/bots/lark/lark_11.png) + +プライベートチャットでも直接使用できます + +![alt text](/assets/image/zh/deploy/bots/lark/lark_12.png) + +## よくある問題 +- ストアアプリのボットは、作成/保存直後にチャットメッセージに応答できません。[app_ticket イベント](https://open.feishu.cn/document/server-docs/application-v6/event/app_ticket-events)の遅延メカニズムにより、正常に動作するまで約 2 分待つ必要があります。 diff --git a/docs/ja/deploy/platforms/line.md b/docs/ja/deploy/platforms/line.md new file mode 100644 index 000000000..b158f337b --- /dev/null +++ b/docs/ja/deploy/platforms/line.md @@ -0,0 +1,153 @@ +# LINE ボットの統合 + +この記事では、LangBot を LINE プラットフォームと接続して LINE ボット機能を実装する方法について説明します。 + +## LINE ボットの作成 + +### LINE 開発者アカウントの登録 + +1. [LINE Developers ウェブサイト](https://developers.line.biz/)にアクセスし、LINE アカウントでログインします +2. ログイン後、開発者コンソールに入ります + +### Provider と Channel の作成 + +> [Developer Console](https://developers.line.biz/console) + +1. 開発者コンソールで、新しい Provider を作成します（ない場合） +![alt text](/assets/image/zh/deploy/bots/line/line01.png) +2. Provider の下で、「Create」をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line02.png) +3. 名前を入力して Create をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line03.png) + +4. リダイレクト後、Message API の作成を選択します +![alt text](/assets/image/zh/deploy/bots/line/line04.png) +* Message API の作成をクリックして続行します +![alt text](/assets/image/zh/deploy/bots/line/line05.png) +* リダイレクト後、基本情報を入力します +![alt text](/assets/image/zh/deploy/bots/line/line06.png) + - Channel Name + - Channel Description + - Category + - Subcategory + - Email Address +5. すべての情報を入力したら、「Continue」をクリックして作成します +![alt text](/assets/image/zh/deploy/bots/line/line07.png) +6. 入力した情報を確認し、問題がなければ Submit をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line08.png) +7. 正常に作成されました。使用に進みます +![alt text](/assets/image/zh/deploy/bots/line/line09.png) + +### 設定情報の取得 + +作成後、次の重要な情報を取得します。記録してください： + +1. Channel Secret +> [使用をクリックした後のページ](https://manager.line.biz/account) +* Settings を選択 +![alt text](/assets/image/zh/deploy/bots/line/line09.png) +* Message API をクリック +![alt text](/assets/image/zh/deploy/bots/line/line11.png) +* Message API を有効にします +![alt text](/assets/image/zh/deploy/bots/line/line12.png) +* 作成したばかりの Provider を選択し、Agree をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line13.png) +* プライバシー規約については、単に OK をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line14.png) +* OK をクリックして作成を完了します +![alt text](/assets/image/zh/deploy/bots/line/line15.png) +* コピーします +![alt text](/assets/image/zh/deploy/bots/line/line16.png) + +2. Channel Access Token（「Issue」ボタンをクリックして生成する必要があります） +* console をクリックするか、直接 [Console](https://developers.line.biz/console/) にアクセスします +![alt text](/assets/image/zh/deploy/bots/line/line17.png) +* 作成した Provider を選択し、Message API をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line18.png) +* Message API をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line19.png) +* 一番下までスクロールし、Issue をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line20.png) +* アイコンをクリックしてコピーします +![alt text](/assets/image/zh/deploy/bots/line/line21.png) + +## LangBot に接続 + +次に、LangBot 設定ページを開きます： + +1. 「Bots」をクリックし、次に「Add」をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line26.png) +2. 「Platform/Adapter Selection」で「LINE」を選択します +![alt text](/assets/image/zh/deploy/bots/line/line27.png) + +3. 設定情報を入力します： + - Channel Secret：以前に取得した Channel secret + - Channel Access Token：以前に取得した Channel access token + ![alt text](/assets/image/zh/deploy/bots/line/line28.png) + +4. 「Save」をクリックして設定を完了します + ![alt text](/assets/image/zh/deploy/bots/line/line29.png) + +## Webhook の設定 + +::: info +まず、[HTTP リバースプロキシの設定](/en/workshop/production/proxy-and-ssl)を参照して LangBot コールバックアドレスを設定することをお勧めします。 +::: + +* LangBot 設定ページから Webhook コールバック URL を取得します +![alt text](/assets/image/zh/deploy/bots/line/line30.png) + +* console をクリックするか、直接 [Console](https://developers.line.biz/console/) にアクセスします +![alt text](/assets/image/zh/deploy/bots/line/line17.png) +* 作成した Provider を選択し、Message API をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line18.png) +* Message API をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line19.png) +* Edit をクリックして接続を入力します +![alt text](/assets/image/zh/deploy/bots/line/line22.png) +* 接続を入力します（HTTPS 接続である必要があります。つまり、SSL 証明書が必要です）、Update をクリックします +![alt text](/assets/image/zh/deploy/bots/line/line23.png) + +* Use Webhook を選択します +![alt text](/assets/image/zh/deploy/bots/line/line24.png) + +5. 「Verify」ボタンをクリックして、接続が成功したかどうかをテストします +![alt text](/assets/image/zh/deploy/bots/line/line25.png) + + +## 機能設定 + +LINE 開発者コンソールで、ボットの機能をさらに設定できます： + +1. 「Messaging API」タブで、「LINE Official Account Features」セクションを見つけます +2. 必要に応じて次の機能を有効または無効にします： + - 自動返信メッセージ + - 友達追加時のウェルカムメッセージ + - グループおよび複数人チャット + - ボットがグループに参加したときの挨拶 + +## 使用方法 + +設定後、ユーザーは次の方法で LINE ボットとやり取りできます： + +1. LINE 開発者コンソールで提供される QR コードをスキャンして、ボットを友達として追加します +2. チャットでメッセージを送信すると、ボットは LangBot を通じて処理して返信します + +## よくある問題 + +### Webhook 検証失敗 + +- サーバーが HTTPS 経由でアクセスできることを確認してください +- Webhook URL が正しいかどうかを確認してください +- LangBot サービスが正常に実行されていることを確認してください + +### メッセージを受信できない + +- Channel Access Token が有効かどうかを確認してください +- 「Use Webhook」オプションが有効になっていることを確認してください +- LangBot ログでエラーメッセージを確認してください + +### 権限の問題 + +- LINE 開発者コンソールでボットに必要な権限を有効にしていることを確認してください +- 一部の高度な機能には、LINE Premium アカウントが必要な場合があります diff --git a/docs/ja/deploy/platforms/qq/aiocqhttp/lagrange.md b/docs/ja/deploy/platforms/qq/aiocqhttp/lagrange.md new file mode 100644 index 000000000..3de463164 --- /dev/null +++ b/docs/ja/deploy/platforms/qq/aiocqhttp/lagrange.md @@ -0,0 +1,67 @@ +# メッセージプラットフォーム Lagrange のデプロイ + +## Lagrange の紹介 + +Lagrange は、軽量で比較的安定した QQNT プロトコルリバースエンジニアリングフレームワークです。OneBot 11 プロトコルを通じて接続します。アダプターとして `OneBot v11` を選択する必要があります。 + +::: warning +ボットとやり取りするには NT QQ を使用する必要があります。古いバージョンの QQ は正常に動作しません +::: + +## デプロイ手順 + +以下は Windows の一般的な手順のみを提供します。詳細な手順または他のプラットフォームについては、[Lagrange 公式ドキュメント](https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/)を参照してください + +### 環境設定 + +.NET 8 ランタイムをインストールします。[ここをクリックして Microsoft の公式ウェブサイトから直接ダウンロード](https://dotnet.microsoft.com/zh-cn/download/dotnet/thank-you/runtime-desktop-8.0.4-windows-x64-installer) + +### Github Actions から最新のビルドをダウンロード + +Github にログインしてダウンロードする必要があります。特定の機能が必要ない場合は、Release からダウンロードできます。画像 3 を参照してください + +[Github Actions](https://github.com/KonataDev/Lagrange.Core/actions) + +画像に従ってダウンロードします： + +![Image 1](/assets/image/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_1.png) + +![Image 2](/assets/image/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_2.png) + +![Image 3](/assets/image/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_3.png) + +### 最終ステップ + +ダウンロードした zip を解凍し、Lagrange.OneBot.exe を含むディレクトリに移動し、このディレクトリで cmd コマンドプロンプトを開き、次のように入力します + +```bash +.\Lagrange.OneBot +``` + +一度実行します。QR コードが出力された場合、ボットアカウントで直接スキャンしてログインできます（QR コードが不鮮明な場合は、lagrange data ディレクトリで画像ファイルを探すことができます）。 + +ログインできない場合は、lagrange 設定ファイル appsettings.json で署名アドレス SignServerUrl を正しく入力したかどうかを確認してください。署名アドレスは lagrange ドキュメントで確認してください。 + +## 設定の変更 + +Lagrange を LangBot に接続するように設定する必要があります。Lagrange の設定ファイル appsettings.json を編集し、Implementations の接続設定が以下の画像の内容と一致することを確認してください： + +![Configure Connection](/assets/image/zh/deploy/bots/qq/onebot/lagrange/config_lgr.png) + +Type は `ReverseWebSocket` である必要があります； +Host は LangBot を実行しているホストの IP です。同じホストにある場合は、`127.0.0.1` と記述できます； +Suffix は `/ws` である必要があります； + +## Lagrange 統合 + +次に、LangBot 設定ページを開きます + +Bots をクリックし、次に Add をクリックします + +`Platform/Adapter Selection` で `OneBot v11` を選択します + +![napcat_webui_03](/assets/image/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png) + +::: info +注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](/en/workshop/network-details)を参照してください +::: diff --git a/docs/ja/deploy/platforms/qq/aiocqhttp/llonebot.md b/docs/ja/deploy/platforms/qq/aiocqhttp/llonebot.md new file mode 100644 index 000000000..8de533a83 --- /dev/null +++ b/docs/ja/deploy/platforms/qq/aiocqhttp/llonebot.md @@ -0,0 +1,27 @@ +# メッセージプラットフォーム LiteLoaderQQNT のデプロイ + +OneBot 11 プロトコルを通じて接続します。アダプターとして ``OneBot v11`` を選択する必要があります。 + +# LiteLoaderQQNT + +- [LiteLoaderQQNT の OneBot API プラグイン](https://github.com/LLOneBot/LLOneBot)は QQ クライアントに注入し、OneBot 11 プロトコルに変換します + +LiteLoaderQQNT のインストールチュートリアル：https://llonebot.github.io/zh-CN/guide/getting-started + +![Image 1](/assets/image/zh/deploy/bots/qq/onebot/llonebot/llob_cfg.png) + +アドレスの IP アドレスが LangBot を実行しているホストのアドレスであることを確認してください（同じネットワークで実行している場合は、127.0.0.1 を使用します） + +## Lagrange 統合 + +次に、LangBot 設定ページを開きます + +Bots をクリックし、次に Add をクリックします + +`Platform/Adapter Selection` で `OneBot v11` を選択します + +![napcat_webui_03](/assets/image/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png) + +::: info +注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](/en/workshop/network-details)を参照してください +::: diff --git a/docs/ja/deploy/platforms/qq/aiocqhttp/napcat.md b/docs/ja/deploy/platforms/qq/aiocqhttp/napcat.md new file mode 100644 index 000000000..701bad15b --- /dev/null +++ b/docs/ja/deploy/platforms/qq/aiocqhttp/napcat.md @@ -0,0 +1,33 @@ +# メッセージプラットフォーム NapCat のデプロイ + +OneBot 11 プロトコルを通じて接続します。アダプターとして ``OneBot v11`` を選択する必要があります。 + +## NapCat インストールチュートリアル + +[NapCat 公式ドキュメントに従ってインストール](https://napcat.napneko.icu/guide/start-install)してください + +## NapCat 設定チュートリアル + +webui 操作のみを例として使用します。他の設定方法については、NapCat ドキュメントを確認してください。 + +ログイン後、コンソールまたは Bash でログを確認し、`[NapCat] [WebUi] WebUi Publish Panel Url: http://x.x.x.x:6099/webui?token=xxxxx ` を見つけます +![napcat_webui_01](/assets/image/zh/deploy/bots/qq/onebot/napcat/napcat_webui_01.png) + +Url をブラウザにコピーするか、Windows 11 では Ctrl を押しながら Url をクリックします。QR コードをスキャンしてログインすると、ネットワーク設定ページに入ります。 + +ネットワーク設定を追加をクリックし、WebSocket Client を選択し、有効をクリックして、Url フィールドに `ws://127.0.0.1:2280/ws` を入力して保存します。 +![napcat_webui_02](/assets/image/zh/deploy/bots/qq/onebot/napcat/napcat_webui_02.png) + +## NapCat 統合 + +次に、LangBot 設定ページを開きます + +Bots をクリックし、次に Add をクリックします + +`Platform/Adapter Selection` で `OneBot v11` を選択します + +![napcat_webui_03](/assets/image/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png) + +::: info +注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](/en/workshop/network-details)を参照してください +::: diff --git a/docs/ja/deploy/platforms/qq/official_webhook.md b/docs/ja/deploy/platforms/qq/official_webhook.md new file mode 100644 index 000000000..df7a114d3 --- /dev/null +++ b/docs/ja/deploy/platforms/qq/official_webhook.md @@ -0,0 +1,80 @@ +# QQ 公式ボット API の使用（Webhook 方式を使用） + +この記事では、テストボットのデプロイのみを提供します。ボットの正式な起動については、[リリースプロセス](https://q.qq.com/qqbot/#/home)に従ってください。 + +:::warning +QQ 公式は、AIGC 機能への不正アクセスを禁止する発表を行いました。注意して使用してください。 +::: + + + +## QQ ボットの登録（テストボット） + +### 基本ボット情報の設定 + +[QQ Open Platform](https://q.qq.com/#/)にアクセスし、下部の「アプリケーション管理」を見つけ、ボットを作成をクリックし、基本情報を入力して、ボットページに入ります。以下のように： + +![Bot Main Page](/assets/image/zh/deploy/bots/qq/official/qqofficial1.png) + +「ホーム」オプションの「リリースプロセス」は、ボットを起動する手順です。テストバージョンのボットをデプロイしているため、「情報」と「サンドボックス設定」セクションを完了するだけで済みます。
+ +まず情報を入力し、次にサンドボックス設定をクリックします。 + +#### サンドボックス設定の構成 + +「サンドボックス設定」をクリックします。 +QQ グループにデプロイする場合は、「QQ グループ ID」の下の要件に従ってグループチャットを選択し、メッセージリスト設定でプライベートチャット権限を持つユーザーを追加します。
+QQ チャンネルにデプロイする場合は、「チャンネル ID」の下の要件に従ってチャンネル ID を選択します。ボットタイプは 0 です。 + +#### 開発管理の構成 + +「開発管理」をクリックします。 + +![Development Management Page](/assets/image/zh/deploy/bots/qq/official/qqofficial2.png) + +「AppID」、「Token」、「AppSecret」を記録し、LangBot が配置されているサーバーの IP アドレスを IP ホワイトリストに追加します。 + +## LangBot に接続 + +次に、LangBot 設定ページを開きます + +Bots をクリックし、次に Add をクリックします + +`Platform/Adapter Selection` で `QQ Official API` を選択します + +![QQ Official Bot Integration with LangBot](/assets/image/zh/deploy/bots/qq/official/qqofficial3.png) + + +## コールバックアドレスの設定 + +LangBot は、パブリック IP アドレスを持つサーバーにデプロイする必要があり、HTTPS が正常に有効になっている必要があります。ドキュメント [HTTP リバースプロキシと SSL の設定](/en/workshop/production/proxy-and-ssl)に従って設定してください。 + + +#### 後続の設定 + +Caddy の起動に失敗した場合は、[Caddy ドキュメント](https://caddy2.dengxiaolong.com/docs/quick-starts/caddyfile)を読むか、LangBot コミュニティグループに参加してヘルプを求めてください。
+ +以下は、考えられる問題の一部です： + +- ポート 443 が開いていない +- ドメインがマシンに解決されていない +- Caddyfile が正常に保存されなかった + +### 管理ポータルのコールバックアドレスの設定 + + +まず **LangBot を起動します**。 + +ボット管理ポータルの「コールバック設定」をクリックし、「イベントを追加」の下のすべてのイベントをチェックします。 + +LangBot 設定ページに移動し、対応する QQ ボットを有効にして選択し、対応するボット設定ページから Webhook コールバックアドレスをコピーし、IP アドレスとポートを Caddy で設定したドメイン名に置き換えて、リクエストアドレスに入力します。 + +画像に示されているように： +![Caddy Documentation](/assets/image/zh/deploy/bots/qq/official/qqofficial4.png) + + +たとえば、ドメインが `testlb.com` の場合、リクエストアドレスに `testlb.com/bots/xxxxxx-xxxxxx` を入力し、設定の確認をクリックします。コールバックアドレスが正常に保存された場合、デプロイは成功です。「検証失敗」が表示された場合は、上記の設定項目が正しく入力されているかどうかを注意深く確認してください。 + +## 公開方法 + +「ホーム」のリリースプロセスに入り、プロセスに従ってボットを公開して起動します。 diff --git a/docs/ja/deploy/platforms/readme.md b/docs/ja/deploy/platforms/readme.md new file mode 100644 index 000000000..6bc62d14e --- /dev/null +++ b/docs/ja/deploy/platforms/readme.md @@ -0,0 +1,22 @@ +# ボットの設定（Bots） + +ボットは、メッセージングプラットフォームからメッセージイベントを受信し、パイプラインを呼び出してメッセージを処理するために使用されます。 + +![arch](/assets/image/zh/deploy/bots/arch.png) + + +| プラットフォーム | ステータス | 備考 | チュートリアル | +| ------ | ---- | ---- | ---- | +| Discord | ✅ | | [チュートリアル](/en/deploy/platforms/discord) | +| Telegram | ✅ | | [チュートリアル](/en/deploy/platforms/telegram) | +| Slack | ✅ | | [チュートリアル](/en/deploy/platforms/slack) | +| LINE | ✅ | | [チュートリアル](/en/deploy/platforms/line) | +| KOOK | ✅ | | [チュートリアル](/en/deploy/platforms/kook) | +| Lark | ✅ | | [チュートリアル](/en/deploy/platforms/lark) | +| DingTalk | ✅ | | [チュートリアル](/en/deploy/platforms/dingtalk) | +| WeCom（Enterprise WeChat） | ✅ | 企業内部ボット | [チュートリアル](/en/deploy/platforms/wecom/wecom) | +| WeCom Intelligent Bot | ✅ | wecom インテリジェントボット | [チュートリアル](/en/deploy/platforms/wecom/wecombot) | +| WeCom Customer Service | ✅ | 企業外部ボット | [チュートリアル](/en/deploy/platforms/wecom/wecomcs) | +| WeChat Official Account | ✅ | WeChat 公式プラットフォームボット | [チュートリアル](/en/deploy/platforms/wxoa) | +| OneBot v11 | ✅ | 個人 QQ アカウントをボットとして使用し、独立したプロトコルクライアントが必要です。OneBot v11 をサポートします | [NapCat](/en/deploy/platforms/qq/aiocqhttp/napcat)
[Lagrange](/en/deploy/platforms/qq/aiocqhttp/lagrange)
[LiteLoaderQQNT](/en/deploy/platforms/qq/aiocqhttp/llonebot) | +| QQ Official Bot | ✅ | QQ Open Platform ボット API に接続します | [チュートリアル](/en/deploy/platforms/qq/official_webhook) | diff --git a/docs/ja/deploy/platforms/slack.md b/docs/ja/deploy/platforms/slack.md new file mode 100644 index 000000000..353a71398 --- /dev/null +++ b/docs/ja/deploy/platforms/slack.md @@ -0,0 +1,53 @@ +# Slack ボットに接続 + +## ボットの作成 + +[Slack App Platform](https://api.slack.com/apps)にアクセスします。 + +![Slack Platform](/assets/image/zh/deploy/bots/slack/slack_01.jpg) + +右上の「Create New App」をクリックし、「from a manifest」を選択し、ボットをデプロイするワークスペースを選択し、next を選択して、ボットを作成します。 + +左側の「Basic Information」オプションに入り、`signing_secret` を記録します。 + +左側の「OAuth & Permissions」に入り、「Scopes」までスクロールダウンし、次のボット権限を追加します： + +![Bot Permissions 1](/assets/image/zh/deploy/bots/slack/slack_02.jpg) + + +![Bot Permissions 2](/assets/image/zh/deploy/bots/slack/slack_03.jpg) + +上記の権限を追加した後、「Install to your workspace」をクリックし、`xoxb-xxxxx` で始まるトークンを記録します。
+ +**注意：** +**すべての権限を一度に追加しなかった場合は、後で App を再インストールする必要があります。**
+ +左側の「App Home」タブに入り、一番下までスクロールして「Message Tab」を見つけ、オンにして +「Allow users to send Slash commands and messages from the messages tab」をチェックします。 + +## LangBot に接続 + +左側の「Event Subscriptions」に入り、スイッチをオンにし、「Subscribe to bot events」をクリックし、 +次の権限を追加します： +![Event Permissions](/assets/image/zh/deploy/bots/slack/slack_04.jpg) + +上記のすべての操作を完了した後、LangBot Webui 設定ページを開き、新しいボットを追加します + +![Event Permissions](/assets/image/zh/deploy/bots/slack/connect_to_langbot.png) + +## ボットの起動 + +::: info +Slack 公式が https を要求しているため、まずドキュメント [HTTP リバースプロキシと SSL の設定](/en/workshop/production/proxy-and-ssl)に従ってリバースプロキシを設定してください。 +::: + +Slack 設定項目を入力した後、**LangBot を起動します**。 +LangBot ホームページで Slack ボットを有効にして開き、ボット設定ページから WebHook URL をコピーし、先ほど設定した Event Subscriptions の「Request URL」に WebHook URL を入力します。 + + +上記のすべての設定項目を入力した後、リンクを保存をクリックします。緑色の **Verified** が表示されれば、デプロイは成功です。 +それ以外の場合は、上記の設定項目が正しく入力されているかどうかを確認してください。 + +## 効果のデモンストレーション + +![Effect Demonstration](/assets/image/zh/deploy/bots/slack/slack_05.jpg) diff --git a/docs/ja/deploy/platforms/telegram.md b/docs/ja/deploy/platforms/telegram.md new file mode 100644 index 000000000..713fedabd --- /dev/null +++ b/docs/ja/deploy/platforms/telegram.md @@ -0,0 +1,29 @@ +# Telegram ボットに接続 + +## ボットの作成 + +[Telegram Bot Creation Page](https://t.me/botfather)にアクセスし、プロンプトに従ってボットを作成します。 + +![Telegram Bot Creation](/assets/image/zh/deploy/bots/telegram/telegram_01.png) + +![Telegram Bot Creation](/assets/image/zh/deploy/bots/telegram/telegram_02.png) + +作成後、BotFather は API Token を返しますので、安全に保管してください。次に、グループチャットで使用するために「Privacy Mode」をオフにします。 + +![Telegram Bot API Token](/assets/image/zh/deploy/bots/telegram/telegram_03.png) + +## LangBot に接続 + +LangBot Webui ページを開き、新しいボットを作成します + +![Connect to LangBot](/assets/image/zh/deploy/bots/telegram/connect_to_langbot.png) + +入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: telegram` と表示されます。LangBot を実行し続けてください。 + +## ボットの使用 + +グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。 + +![Telegram Bot Usage](/assets/image/zh/deploy/bots/telegram/telegram_04.png) + +![Telegram Bot Usage](/assets/image/zh/deploy/bots/telegram/telegram_05.png) diff --git a/docs/ja/deploy/platforms/wecom/wecom.md b/docs/ja/deploy/platforms/wecom/wecom.md new file mode 100644 index 000000000..66a50bddb --- /dev/null +++ b/docs/ja/deploy/platforms/wecom/wecom.md @@ -0,0 +1,70 @@ +# WeCom ボットのデプロイ + +WeCom（Enterprise WeChat）ボットをデプロイして LangBot に接続します。 + +:::info +この統合方法は、企業内部アプリケーション用であり、企業内で使用されます。外部カスタマーサービスが必要な場合は、[WeCom Customer Service 統合ソリューション](wecomcs.md)を確認してください。 +::: + + +## ボットの作成 + +[WeCom Admin Portal](https://work.weixin.qq.com/)に入り、アカウントにログインし、メインページに入った後、「アプリ管理」、「独自の構築」、「アプリを作成」をクリックし、ボットの基本情報を入力します。作成後、次のようなページが表示されます： +![Bot Page](/assets/image/zh/deploy/bots/wecom/wecom/wecom1.png) + +## コールバックアドレスの設定 + +### WeCom 設定項目の取得 + +1. WeCom Admin Portal ホームページを開き、「私の企業」をクリックし、下部の Enterprise ID を記録します。 + +![Enterprise ID](/assets/image/zh/deploy/bots/wecom/wecom/wecom2.png) + +2. 連絡先同期権限を有効にします + +:::info +- この設定項目は、LangBot の一斉送信機能を実装するためのものです。具体的なコードは libs/wecom_api/api.py にあります。 +- LangBot はまだ開発中であるため、この設定項目に関連する機能はまだ実装されていません。 +- この設定項目はランダムな文字で埋めることができますが、**空にすることはできません**。 +::: + +![Contact Permission](/assets/image/zh/deploy/bots/wecom/wecom/wecom5.png) + +「セキュリティと管理」、「管理ツール」、「連絡先同期」をクリックします + +![Contact Sync Secret](/assets/image/zh/deploy/bots/wecom/wecom/wecom3.jpg) + +「Secret を表示」をクリックして記録します。これが contacts_secret（連絡先同期 Secret）です。 + +3. 「アプリ管理」をクリックし、作成したばかりのボットを見つけ、ボットの secret を表示して記録します。 + +![Bot Secret](/assets/image/zh/deploy/bots/wecom/wecom/wecom4.png) + +この時点で、3 つの設定項目を取得しました：corpid（Enterprise ID）、secret（Bot Secret）、contacts_secret（Contact Sync Secret）。 + +### コールバックアドレスの設定 + +ボットページに入ります。 + +下部の「企業信頼 IP」をクリックし、LangBot がデプロイされているサーバーを追加します。 + +「メッセージを受信」、「API 受信を設定」をクリックし、サーバーメッセージ受信設定を開始します。 + +LangBot ホームページで、対応するボットを有効にして選択し、設定ページをクリックして入り、Webhook コールバックアドレスをコピーして URL に入力します。 + +::: info +まず、[HTTP リバースプロキシの設定](/en/workshop/production/proxy-and-ssl)を参照して LangBot コールバックアドレスを設定することをお勧めします。 +::: + +![Webhook Callback Address](/assets/image/zh/deploy/bots/wecom/wecom/wecom6.png) + +Token と EncodingAESKey をランダムに生成するためにクリックし、それらを記録します + +## LangBot に接続 + +![Connect to LangBot](/assets/image/zh/deploy/bots/wecom/wecom/connect_to_langbot.png) + +## コールバックアドレスの保存 +上記の 5 つの設定項目が正しく取得され、WeCom アダプターに正確に入力されたら、**LangBot を起動します**。 + +コールバックアドレス設定ページに戻り、保存をクリックします。上記の設定項目が正しく入力されている場合、保存は成功します。これは、WeCom と LangBot が通信できることを意味します（デプロイ成功）。**openapi request callback address failed** が表示された場合は、設定項目が正しく入力されているかどうかを 3 回確認してください。 diff --git a/docs/ja/deploy/platforms/wecom/wecombot.md b/docs/ja/deploy/platforms/wecom/wecombot.md new file mode 100644 index 000000000..7587e66a5 --- /dev/null +++ b/docs/ja/deploy/platforms/wecom/wecombot.md @@ -0,0 +1,59 @@ +# WeCom インテリジェントボットのデプロイ + + +## ボットの作成 + +まず、[WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/)にログインします。 + +![Homepage](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_1.png) + +左側のサイドバーの「セキュリティと管理」をクリックし、次に「管理ツール」の下の「インテリジェントボット」をクリックします。 + +以下のように： + +![Intelligent Bot](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_2.png) + +「ボットを作成」をクリックし、ページの一番下までスクロールして「API モードで作成」をクリックし、ページに入ります： + +![Create via API Mode](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_3.png) + +Token と EncodingAESKey をランダムに生成するためにクリックし、次に上部に基本的なボット情報を入力します。**表示範囲の設定に注意してください**。 + +左側のサイドバーの「私の会社」をクリックし、下部の会社 ID を保存します。 + +## コールバック URL の設定 + +LangBot メインプログラムを起動し、アダプター「WeCom Intelligent Bot」を選択し、設定項目を入力します。 +その中で、token は Token、Encoding-AESKey は EncodingAESKey、Bot ID は xxx として入力できます（またはランダムに入力でき、後で変更されます）。入力後、 +「保存」をクリックし、ロボットを「有効化」します。 + +![WeCom Intelligent Bot Adapter](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_4.png) + +LangBot ホームページで、対応するボットを有効にして選択し、設定ページをクリックして入り、Webhook コールバックアドレスをコピーします + +::: info +まず、[HTTP リバースプロキシの設定](/en/workshop/production/proxy-and-ssl)を参照して LangBot コールバックアドレスを設定することをお勧めします。 +::: + +![Webhook Callback Address](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_8.png) + +WeCom ロボット設定ページに戻り、コピーした webhook アドレスを「URL Callback」に入力します。作成が成功すると、詳細ページにジャンプします。「Request URL Failed」というメッセージが表示された場合は、上記の手順が 1 つずつ完了しているかどうかを再度確認してください。 + +作成成功後の詳細ページ： +![Creation Successful](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_5.png) + +WeCom ロボット詳細ページから「Bot ID」をコピーし、LangBot 管理ページに戻り、デプロイされたインテリジェントロボットの Bot ID をコピーした ID に変更し、ロボットを再起動します。 + +## 使用開始 + +WeCom に入り、「➕」をクリックします。以下のように： + +![Add Bot](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_6.png) + +「会社作成」をクリックし、作成したボットを選択し、チャットインターフェイスに入ります。 + +同様に、ボットをグループチャットに招待したい場合は、グループチャットでメンバーを追加ボタンをクリックし、そこからボットを追加します。 + +## 効果の画像 + +![Effect Image 1](/assets/image/zh/deploy/bots/wecom/wecombot/wecombot_7.png) diff --git a/docs/ja/deploy/platforms/wecom/wecomcs.md b/docs/ja/deploy/platforms/wecom/wecomcs.md new file mode 100644 index 000000000..b058c940c --- /dev/null +++ b/docs/ja/deploy/platforms/wecom/wecomcs.md @@ -0,0 +1,25 @@ +# WeCom Customer Service のデプロイ + +:::info + +この記事では、LangBot を WeCom カスタマーサービスアカウントにデプロイするプロセスについて詳しく説明します。これにより、カスタマーサービスアカウントと通常の WeChat との間の会話が可能になります。WeCom 内でのみ使用する必要がある場合は、[WeCom 内部アプリケーションの実装](wecom.md)を参照してください。 + +**WeCom カスタマーサービスアカウントのデプロイには企業資格が必要です**。[WeCom Customer Service 統合ガイド](https://developer.work.weixin.qq.com/document/path/94638)を確認し、このドキュメントに従って対応する企業資格証明書を提供してください。 + +::: + +## 効果のデモンストレーション + +![Effect Demonstration](/assets/image/zh/deploy/bots/wecom/wecomcs/wecomcs_01.jpg) + +## LangBot に接続 + +![Connect to LangBot](/assets/image/zh/deploy/bots/wecom/wecomcs/connect_to_langbot.png) + +後続の設定方法と設定項目は [WeCom 内部アプリケーション](wecom.md)と同じですが、`contacts_secret` は必要ありません。 + +## 注意事項 + +1. 上記の WeCom 公式ドキュメントの手順に必ず従い、カスタマーサービスアカウントを「API 管理」に追加してください。 +2. 手順は WeCom 内部アプリケーションと同じです。何も見逃さないでください。基本的には WeCom 内部アプリケーションに他の権限を追加するだけなので、コールバックアドレスも保存する必要があります。 +3. LangBot は、チャット記録や企業資格コンテンツなどの機密情報を読み取りません。 diff --git a/docs/ja/deploy/platforms/wxoa.md b/docs/ja/deploy/platforms/wxoa.md new file mode 100644 index 000000000..2a9aabb21 --- /dev/null +++ b/docs/ja/deploy/platforms/wxoa.md @@ -0,0 +1,51 @@ +# WeChat Official Account ボットのデプロイ + +WeChat Official Account ボットをデプロイして LangBot に接続します。 + +## LangBot WeChat Official Account 統合モード + +現在、LangBot は WeChat Official Accounts と統合する 2 つの方法を提供しています： + +1. **従来のメッセージ交換モード** + - 公式アカウントはリクエストを **15 秒**以内に処理する必要があり、このタイムアウトを超える AI 生成コンテンツは送信できません。 + - AI コンテンツ生成のタイムアウトが発生すると、LangBot はコンソールにリクエストタイムアウト情報を出力します。 + +2. **「任意のテキストを送信して返信を取得」モード** + - この方法は **15 秒**の制限を破ることができますが、**非常に長いテキスト**は正常に送信されない場合があります。 + - この方法を使用する場合、公式アカウントにメッセージを送信すると、「AI が考えています。回答を得るには任意のコンテンツを送信してください」と返信されます。この時点で、回答を得るために任意のコンテンツを送信する必要があります。 + +より複雑な機能については、カスタマイズされたサポートのために **LangBot チーム**にお問い合わせください。 + +## ボットの作成 + +[WeChat Official Account Platform](https://mp.weixin.qq.com/)に入り、すでに公式アカウントをお持ちの場合は、QR コードをスキャンしてログインしてコンソールに入ります。 +以前に公式アカウントを登録したことがない場合は、今すぐ登録をクリックし、「公式アカウント」を選択し、順番に情報を入力し、コンソールに入ります。コンソールは次のようになります： +![Console Page](/assets/image/zh/deploy/bots/wxoa/wxoa1.png) + + +## コールバックアドレスの設定 + +### 設定項目の取得 + +「設定と開発」、「開発インターフェイス管理」をクリックすると、次のようなページが表示されます： +![Set Development Items](/assets/image/zh/deploy/bots/wxoa/wxoa2.png) + +「開発者 ID（AppID）」、「開発者パスワード（AppSecret）」を記録し、LangBot がデプロイされているサーバーを「IP ホワイトリスト」に追加します。 + +### LangBot のリバースプロキシの設定 + +WeChat Official Accounts は http（ポート 80）と https（ポート 443）のみをサポートしているため、ドキュメント [HTTP リバースプロキシと SSL の設定](/en/workshop/production/proxy-and-ssl)に従って設定してください。 + +### コールバックアドレスの保存 + +サーバー設定を設定をクリックし、「Token」、「EncodingAESKey」を入力し、メッセージの暗号化/復号化方式を「Safe Mode」に変更します。 + +この時点で、LangBot Webui ページを開き、新しいボットを作成し、取得した 4 つの設定項目（AppID、AppSecret、token、EncodingAESKey）を入力します + +![Set Development Items](/assets/image/zh/deploy/bots/wxoa/connect_to_langbot.png) + +設定項目の「Mode」オプションは、選択された統合モードです。デフォルトは「drop」です。「drop」は従来のメッセージ交換モードで、「passive」は「任意のテキストを送信して返信を取得」モードです。 + +「LoadingMessage」オプションはローディングメッセージで、他のコンテンツに変更でき、モードが「passive」の場合にのみ有効です。「enable」を「true」に設定します。 + +正常に入力した後、LangBot ホームページで対応するボットを有効にして選択し、設定ページをクリックして入り、Webhook コールバックアドレスをコピーし、WeChat Official Account ボット設定ページに戻って「URL」に入力します。たとえば、URL を「https://your_domain_name/bots/xxxxx」として入力します。ここで「your_domain_name」は Caddy に入力したドメイン名です。保存をクリックします。正常に保存できれば、デプロイは成功です。**システムエラー、後でもう一度お試しください**が表示された場合は、上記の設定内容が正しく入力されているかどうかを再確認してください。 diff --git a/docs/ja/deploy/settings.md b/docs/ja/deploy/settings.md new file mode 100644 index 000000000..359a9a40f --- /dev/null +++ b/docs/ja/deploy/settings.md @@ -0,0 +1,152 @@ +# システム環境設定 + +システム動作のための環境情報を設定します。`data/config.yaml`ファイルに配置されています。 +通常、変更は必要ありません。 + +```yaml +# 管理者セッションリスト、コマンド処理時のみ有効 +# 形式はセッションID(person_xxxxまたはgroup_xxxx) +# セッションIDはメッセージ送信時のコンソールログで確認できます +# 例: +# admins: +# - person_1234567890 +# - group_1234567890 +admins: [] + +# APIポート +api: + port: 5300 + # LangBotはWebhookリスニングを必要とするすべてのボットアドレスを一元管理します + # これはWebhook接続を必要とするボットページに表示されるWebhookアドレスプレフィックスです + # ネットワーク環境に応じて変更できます + webhook_prefix: 'http://127.0.0.1:5300' + +# コマンド設定 +command: + # コマンドプレフィックス、これらのプレフィックスを持つメッセージはコマンドとして認識されます + prefix: + - '!' + - ！ + + # コマンド権限設定、キーはコマンドプレフィックス、値は権限タイプ + privilege: {} + +# 同時実行設定 +concurrency: + # 単一パイプライン同時実行 + pipeline: 20 + # 単一セッション同時実行 + session: 1 + +# データベース設定 +database: + # 使用するデータベース + # サポートされているデータベース: + # - sqlite (ローカルSQLiteデータベース、デフォルト) + # - postgresql (PostgreSQLデータベース、以下で設定してください) + use: sqlite + # SQLite設定 + sqlite: + path: 'data/langbot.db' + # PostgreSQL設定 + postgresql: + host: '127.0.0.1' + port: 5432 + database: 'postgres' + user: 'postgres' + password: 'postgres' + +# プラグインシステム設定 +plugin: + # プラグインシステムを有効にするか + enable: true + # プラグインランタイムWebSocketアドレス + # Docker環境のデフォルト値 + # スタンドアロンのPlugin Runtimeを使用する場合は、https://docs.langbot.app/en/develop/plugin-runtime.htmlを参照してください + runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws' + # プラグインマーケットプレイスを有効にするか + enable_marketplace: true + # プラグインマーケットプレイスURL + cloud_service_url: 'https://space.langbot.app' + +# プロキシ設定 +proxy: + # HTTPプロキシアドレス + # プロキシが既に環境変数に設定されている場合、設定は不要です + # 例: + # proxy: + # http: 'http://127.0.0.1:7890' + # https: 'http://127.0.0.1:7890' + http: '' + https: '' + +# オブジェクトストレージ設定 +storage: + # 使用するオブジェクトストレージ + # サポートされているオブジェクトストレージ: + # - local (ローカルストレージ、デフォルト) + # - s3 (S3プロトコルオブジェクトストレージ、R2、MinIOなどをサポート。以下で設定してください) + use: local + # S3設定 + s3: + endpoint_url: '' + access_key_id: '' + secret_access_key: '' + region: 'us-east-1' + bucket: 'langbot-storage' + +# システム設定 +system: + # JWT設定 + jwt: + # JWT有効期限(秒) + expire: 604800 + # JWTシークレットキー、最初の起動時に自動生成されます + secret: 'xxxx' + +# ベクトルデータベース設定 +vdb: + # 使用するベクトルデータベース + # サポートされているベクトルデータベース: + # - chroma (デフォルト、組み込みベクトルデータベース) + # - qdrant (外部ベクトルデータベース、以下で設定してください) + # - milvus (スケーラブルベクトルデータベース、以下で設定してください) + # - pgvector (PostgreSQL拡張、以下で設定してください) + use: chroma + # Qdrant設定 + qdrant: + # Qdrant URL + url: '' + # Qdrant Host + host: localhost + # Qdrant Port + port: 6333 + # Qdrant API Key + api_key: '' + # Milvus設定 + milvus: + uri: 'http://127.0.0.1:19530' + token: '' + # pgvector設定 + pgvector: + host: '127.0.0.1' + port: 5433 + database: 'langbot' + user: 'postgres' + password: 'postgres' +``` + +## 環境変数による設定 + +`config.yaml`の設定は環境変数を介して設定できます。環境変数名は大文字で、二重アンダースコアで接続されます。例: `API__PORT`は`api.port`を表します。 + +- `API__PORT`は`api.port`を表します +- `CONCURRENCY__PIPELINE`は`concurrency.pipeline`を表します +- `CONCURRENCY__SESSION`は`concurrency.session`を表します +- `DATABASE__POSTGRESQL__DATABASE`は`database.postgresql.database`を表します +- `DATABASE__POSTGRESQL__HOST`は`database.postgresql.host`を表します +- `DATABASE__SQLITE__PATH`は`database.sqlite.path`を表します + +... + +起動時、LangBotはすべての環境変数を読み取り、対応する設定を`config.yaml`に適用して`data/config.yaml`ファイルに書き込みます。 diff --git a/docs/ja/deploy/update.md b/docs/ja/deploy/update.md new file mode 100644 index 000000000..ad1858204 --- /dev/null +++ b/docs/ja/deploy/update.md @@ -0,0 +1,35 @@ +# LangBotの更新 + +## パッケージマネージャーを使用 + +LangBotをデプロイしたディレクトリで再度実行してください: + +```bash +uvx langbot@latest +``` + +このコマンドは最新バージョンのLangBotをダウンロードして起動します。 + +## Dockerを使用(またはDockerベースのワンクリックデプロイ) + +LangBotをクローンしたディレクトリで実行してください: + +```bash +git pull +``` + +`docker/`ディレクトリで実行してください: + +```bash +docker compose up --force-recreate --pull always -d +``` + +このコマンドは最新のLangBotイメージをプルしてコンテナを再構築します。 + +:::info +4.3.0バージョンでは`docker-compose.yaml`ファイルの内容と場所が変更されました。以前のバージョンから更新した場合は、[ドキュメントに従って再デプロイ](/en/deploy/langbot/docker)してください。 +::: + +## 手動デプロイ + +[リリース](https://github.com/langbot-app/LangBot/releases)ページのAssetsセクションから最新リリースの`langbot--all.zip`をダウンロードし、元のデプロイディレクトリに展開して再起動してください。 diff --git a/docs/ja/develop/comp-arch.md b/docs/ja/develop/comp-arch.md new file mode 100644 index 000000000..f9ccb87de --- /dev/null +++ b/docs/ja/develop/comp-arch.md @@ -0,0 +1,3 @@ +# コンポーネントアーキテクチャ + +![コンポーネントアーキテクチャ図](/assets/image/zh/develop/comp_arch/develop_comp_arch_1.png) diff --git a/docs/ja/develop/dev-config.md b/docs/ja/develop/dev-config.md new file mode 100644 index 000000000..14ffdd69e --- /dev/null +++ b/docs/ja/develop/dev-config.md @@ -0,0 +1,63 @@ +# 開発設定 + +LangBotはフロントエンドとバックエンドに分かれています。フロントエンドはNext.js + shadcnを使用して開発され、バックエンドはQuart(Flaskの非同期版)を使用して開発されています。 + +## バックエンド + +コードは`pkg`ディレクトリにあり、ルートディレクトリの`main.py`ファイルによって起動されます。 + +依存関係をインストールします。依存関係の管理にはuvを使用します。 + +```bash +pip install uv +uv sync --dev +``` + +バックエンドを起動します + +```bash +uv run main.py +``` + +この時点で、設定ファイルは`data/config.yaml`ファイルに自動的に生成されます。 + +## フロントエンド + +コードは`web`ディレクトリにあり、Node.jsと[pnpm](https://pnpm.io/installation)が必要です。 + +`.env.example`を`.env`にコピーして、値を入力します。 + +- Linuxおよびその他の環境での使用 + +```bash +cp .env.example .env +``` + +- Windows環境での使用 + +```bash +copy .env.example .env +``` + +依存関係をインストールしてフロントエンドを起動します + +```bash +pnpm install +pnpm dev + +# pnpmがインストールされていない場合は、npmを使用して依存関係を解決して起動することもできます +npm install +npm run dev +``` + +その後、出力情報に従って、`http://127.0.0.1:3000`にアクセスして、スタンドアロンフロントエンドページを表示します。 + +:::info +`pnpm dev`を使用してローカルで起動すると、環境変数`NEXT_PUBLIC_API_BASE_URL`がフロントエンドによって自動的に使用され、フロントエンドがローカルで実行中のバックエンドの`5300`ポートにアクセスできるようになります。 + +本番環境では、フロントエンドは静的ファイルにプリコンパイルされ、バックエンドによって提供され、フロントエンドは同じドメインのバックエンドアドレスに自動的にアクセスします。 +::: + +## APIドキュメント + +各インターフェースを開発する前に、APIFoxでAPIドキュメントを作成します。[APIドキュメント(中国語)](https://ok52vhsenr.apifox.cn/)を参照してください。 diff --git a/docs/ja/develop/plugin-runtime.md b/docs/ja/develop/plugin-runtime.md new file mode 100644 index 000000000..8f038b18b --- /dev/null +++ b/docs/ja/develop/plugin-runtime.md @@ -0,0 +1,72 @@ +# プラグインランタイム、CLI、SDKのデバッグ + +::: info +まず[プラグインチュートリアル](/en/plugin/plugin-intro)を読んで、プラグインシステムを理解してください。 + +- プラグインランタイム、CLI、SDKはこちらでオープンソース化されています: https://github.com/langbot-app/langbot-plugin-sdk +::: + +プラグインランタイムのソースコードをクローンします: + +```bash +git clone https://github.com/langbot-app/langbot-plugin-sdk +``` + +プラグインランタイムディレクトリに移動し、依存関係をインストールします: + +```bash +cd langbot-plugin-sdk +uv sync --dev +``` + +この時点で、uvは自動的に仮想環境(.venv)を作成します。エディターがこの仮想環境を使用するかどうかを尋ねる場合は、`Yes`を選択してください。 + +または、この仮想環境を手動でアクティブ化できます: + +```bash +source .venv/bin/activate +``` + +## プラグインランタイムの起動 + +```bash +lbp rt +``` + +`lbp`コマンドがこのディレクトリの仮想環境の`lbp`実行可能ファイルであることを確認するか、`python -m langbot_plugin.cli.__init__ rt`で起動してください。 + +プラグインランタイムは以下のパラメーターを受け入れます: + +- `--debug-only`: `data/plugins`ディレクトリのプラグインを起動せず、デバッグ接続を通じたプラグインの読み込みのみを許可します。 +- `--ws-debug-port`: リッスンするデバッグポート、デフォルトは`5401`です。 +- `--ws-control-port`: リッスンする制御ポート(LangBotメインプログラム接続用)、デフォルトは`5400`です。 +- `-s`: `stdio`を使用して制御接続を受け入れます。**本番環境でのみ使用してください**。 +- `--skip-deps-check`: すべてのプラグイン依存関係がインストールされていることを確認するため、ランタイムは起動時に毎回すべてのインストール済みプラグインの依存関係をチェックしてインストールします。このパラメーターを使用してこのチェックを無効にします。 + +### LangBotをこのランタイムに接続する + +LangBotの`data/config.yaml`で`plugin.runtime_ws_url`を`ws://localhost:5400/control/ws`に設定します。 + +```yaml +plugin: + runtime_ws_url: ws://localhost:5400/control/ws +``` + +そして、LangBotメインプログラムの起動時に起動パラメーター`--standalone-runtime`を追加します(例: `uv run main.py --standalone-runtime`)。 +LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。 + +## langbot-plugin-sdkアーキテクチャ + +このコードベースには以下が含まれています: + +- `langbot_plugin.api`: プラグイン関連のエンティティとAPI定義。 +- `langbot_plugin.assets`: プラグインテンプレート。 +- `langbot_plugin.cli`: プラグイン開発CLIツール。 +- `langbot_plugin.entities`: APIで定義されていないプラグインシステム関連のエンティティ。 +- `langbot_plugin.runtime`: プラグインランタイムと基礎通信(stdioおよびwebsocket)の実装。 + +## `lbp` CLIツール + +CLIツールは、ランタイムの起動、プラグインの初期化、プラグインコンポーネント管理、Marketplaceとのインタラクションなどの機能を提供します。 + +詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。 diff --git a/docs/ja/index.md b/docs/ja/index.md new file mode 100644 index 000000000..a7b44606f --- /dev/null +++ b/docs/ja/index.md @@ -0,0 +1,3 @@ + diff --git a/docs/ja/insight/community.md b/docs/ja/insight/community.md new file mode 100644 index 000000000..357a78f61 --- /dev/null +++ b/docs/ja/insight/community.md @@ -0,0 +1,11 @@ +# コミュニティリソース + + +## 簡易チュートリアル +> 簡易チュートリアル:ビデオチュートリアル、より簡単なテキストチュートリアルなど、初心者に適しています + +こちらで収集されています: https://blog.thelazy.top/tags/langbot + +## 🥰 コミュニティ + +Discordコミュニティに参加してください: [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87) diff --git a/docs/ja/insight/features.md b/docs/ja/insight/features.md new file mode 100644 index 000000000..b061114c5 --- /dev/null +++ b/docs/ja/insight/features.md @@ -0,0 +1,78 @@ +# 機能 + +LangBotは、オープンソースのLLMネイティブインスタントメッセージングロボット開発プラットフォームであり、すぐに使えるIMロボット開発体験を提供することを目的としています。Agent、RAG、MCPなどのLLMアプリケーション機能を備え、グローバルなインスタントメッセージングプラットフォームをサポートし、豊富なAPIインターフェースを提供し、カスタム開発をサポートします。 + +## インスタントメッセージングプラットフォームのサポート + +| プラットフォーム | ステータス | 備考 | +| --- | --- | --- | +| 個人QQ | ✅ | | +| QQ公式API | ✅ | | +| WeCom | ✅ | | +| WeComCS | ✅ | | +| WeComIntelligentBot | ✅ | ストリーミング出力をサポート | +| Lark | ✅ | ストリーミング出力をサポート | +| DingTalk | ✅ | ストリーミング出力をサポート | +| Discord | ✅ | | +| Telegram | ✅ | ストリーミング出力をサポート | +| Slack | ✅ | | +| LINE | ✅ | | +| KOOK | ✅ | | +| WhatsApp | 🚧 | | + +🚧: 開発中 + +## モデルとLLMOpsプラットフォームのサポート + +| プロバイダー/サービス | ステータス | 備考 | +| --- | --- | --- | +| [OpenAI](https://platform.openai.com/) | ✅ | 任意のOpenAIインターフェース形式のモデルに利用可能 | +| [DeepSeek](https://www.deepseek.com/) | ✅ | | +| [Moonshot](https://www.moonshot.cn/) | ✅ | | +| [Anthropic](https://www.anthropic.com/) | ✅ | | +| [xAI](https://x.ai/) | ✅ | | +| [Zhipu AI](https://open.bigmodel.cn/) | ✅ | | +| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | LLMおよびGPUリソースプラットフォーム | +| [Dify](https://dify.ai) | ✅ | LLMOpsプラットフォーム | +| [n8n](https://n8n.io/) | ✅ | LLMOpsプラットフォーム | +| [Langflow](https://langflow.org/) | ✅ | LLMOpsプラットフォーム | +| [PPIO](https://ppio.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | LLMおよびGPUリソースプラットフォーム | +| [ShengSuanYun](https://www.shengsuanyun.com/login?code=7DS2QLH5) | ✅ | LLMおよびGPUリソースプラットフォーム | +| [302.AI](https://share.302.ai/SuTG99) | ✅ | LLMゲートウェイ(MaaS) | +| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | | +| [Ollama](https://ollama.com/) | ✅ | ローカルLLM実行プラットフォーム | +| [LMStudio](https://lmstudio.ai/) | ✅ | ローカルLLM実行プラットフォーム | +| [GiteeAI](https://ai.gitee.com/) | ✅ | LLMインターフェースゲートウェイ(MaaS) | +| [SiliconFlow](https://siliconflow.cn/) | ✅ | LLMゲートウェイ(MaaS) | +| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | LLMゲートウェイ(MaaS)、LLMOpsプラットフォーム | +| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | LLMゲートウェイ(MaaS)、LLMOpsプラットフォーム | +| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | LLMゲートウェイ(MaaS) | +| [Coze](https://coze.com) | ✅ | LLMOpsプラットフォーム | + +## LLMアプリケーションパラダイムの実装 + +| アプリケーションパラダイム | ステータス | 備考 | +| --- | --- | --- | +| Agent | ✅ | | +| RAG | ✅ | ベクトルデータベースとしてChromaを使用 | +| MCP | ✅ | StdioおよびHTTPプロトコルをサポート | + +## システムの拡張性 + +- HTTP Service API: APIキー認証を使用して、HTTP APIインターフェースを通じてLangBotのさまざまなエンティティにアクセスすることをサポートします。 +- Outgoing Webhook: Webhookを通じてLangBotの内部イベントを外部システムに送信することをサポートします。 +- プロダクショングレードのプラグインシステム: クロスプロセス通信技術と非同期技術に基づいたプロダクショングレードのプラグインシステムで、さまざまなコンポーネント拡張をサポートします。 + +## ケーススクリーンショット + +![bot_page](/assets/image/zh/insight/features/bot-page.png) + +![create_model](/assets/image/zh/insight/features/create-model.png) + +![edit_pipeline](/assets/image/zh/insight/features/edit-pipeline.png) + +![plugin_market](/assets/image/zh/insight/features/plugin-market.png) + +![private_chat](/assets/image/zh/insight/private_chat.png) + +![group_chat](/assets/image/zh/insight/group_chat.png) diff --git a/docs/ja/insight/guide.md b/docs/ja/insight/guide.md new file mode 100644 index 000000000..e8fad3ba9 --- /dev/null +++ b/docs/ja/insight/guide.md @@ -0,0 +1,39 @@ +# LangBotドキュメントへようこそ + +LangBotは、オープンソースの大規模言語モデル(LLM)ネイティブインスタントメッセージングボットプラットフォームで、複数のメッセージングプラットフォームとモデルプロバイダーをサポートしています。DifyなどのLLMOpsプラットフォームのサポートを提供します。また、ユーザーが迅速にデプロイして使用できるWebUIを提供します。 + +## ドキュメント構成 + +ドキュメントは以下のセクションに分かれています: + +- デプロイと使用(必読): LangBotのデプロイと使用に関する詳細な手順 +- プラグイン: プラグインの使用と開発に関する情報 +- 実践: LangBotの多くの優れたユースケース +- 開発: LangBot開発への参加に関する情報 + +## クイックスタートガイド + +> すぐに始める2つの方法: +> +> - コミュニティリソースの簡易チュートリアルを使用する(左サイドバーを参照) +> - ドキュメントを読んで自分でデプロイする(以下の方法を参照) + +### 1. LangBotをデプロイする + +左側の**LangBotのデプロイ**セクションを読み、LangBotをデプロイする方法を選択してください + +デプロイ後、`http://127.0.0.1:5300`または`http://your-server-public-ip:5300`を開きます + +メールアドレスとパスワードを入力して初期化を完了し、必ず保存してください + +### 2. ボットを設定する + +左サイドバーの[ボットの設定](/en/deploy/platforms/readme)を確認してください + +### 3. モデルを設定する + +左サイドバーの[対話モデルの設定](/en/deploy/models/readme)を確認してください + +
+ +上記の2つのステップを完了すると、LangBotの使用を開始できます。さらに多くの機能を設定する必要がある場合は、[Pipeline](/en/deploy/pipelines/readme)セクションで設定できます diff --git a/docs/ja/plugin/compatibility.md b/docs/ja/plugin/compatibility.md new file mode 100644 index 000000000..9aa7e9786 --- /dev/null +++ b/docs/ja/plugin/compatibility.md @@ -0,0 +1,15 @@ +# システム互換性 + +LangBotのプラグインシステムは、`Asyncio`や`Subprocess`などのメカニズムを利用しています。これらはUnix系システム(LinuxやmacOSなど)では正常に動作しますが、Windowsではいくつかの問題があり、プラグインが正常に動作しない場合があります。 + +PythonのWindowsでの非同期イベントループはデフォルトで`ProactorEventLoop`を使用しますが、このイベントループはStdioのサポートが不足しています。一方、LangBotは非Docker環境においてStdioを使用してPlugin Runtimeと通信し、Plugin Runtimeもプラグインとの通信にStdioを使用します。 + +`SelectorEventLoop`に切り替えた場合、`SelectorEventLoop`は`Subprocess`をサポートしていないため、Plugin Runtimeとプラグインが正常に起動できなくなります。 + +これらの問題の詳細については、次を参照してください: [Python公式ドキュメント](https://docs.python.org/3.13/library/asyncio-platforms.html) + +## 解決策 + +Unix系システムにおけるサブプロセス管理とStdio通信の密結合とは異なり、LangBotとPlugin RuntimeはWindows上で自動的にハイブリッドなサブプロセス + WebSocket通信戦略に切り替わります。LangBotは引き続きサブプロセスを介してPlugin Runtimeを起動しますが、WebSocketで通信します。同様に、Plugin Runtimeは各インストール済みプラグインをサブプロセスで起動しながら、WebSocketを通じて通信します。 + +この動作はOSに基づいて自動的に選択されるため、手動での設定は不要です。 diff --git a/docs/ja/plugin/dev/apis/common.md b/docs/ja/plugin/dev/apis/common.md new file mode 100644 index 000000000..79fec3e63 --- /dev/null +++ b/docs/ja/plugin/dev/apis/common.md @@ -0,0 +1,312 @@ +# プラグイン共通API + +LangBotは、プラグインがさまざまなLangBotモジュールを操作し、メッセージコンテキストを制御するための一連のAPIを提供します。 + +:::info 目次 +[[toc]] +::: + +## リクエストAPI + +現在処理中のユーザーリクエスト(メッセージ)に対する操作です。`EventListener`と`Command`コンポーネントでのみ使用可能です。アクセス方法: + +- `EventListener`のイベントハンドラメソッド内: `event_context: context.EventContext`オブジェクトの内部メソッド +- `Command`のサブコマンドハンドラメソッド内: `context: ExecuteContext`オブジェクトの内部メソッド + +### 直接返信メッセージ + +現在のリクエストが存在するセッションにメッセージチェーンで直接返信します。 + +メッセージチェーンの構築方法については、[メッセージプラットフォームエンティティ](/en/plugin/dev/apis/messages)を参照してください。 + +```python +async def reply( + self, message_chain: platform_message.MessageChain, quote_origin: bool = False +): + """メッセージリクエストに返信する + + Args: + message_chain (platform.types.MessageChain): LangBotメッセージチェーン + quote_origin (bool): 元のメッセージを引用するかどうか + """ + +# 使用例 +await event_context.reply( + platform_message.MessageChain([ + platform_message.Plain(text="Hello, world!"), + ]), +) +``` + +### Bot UUIDの取得 + +現在のリクエストを発行したBotのUUIDを取得します。 + +```python +async def get_bot_uuid(self) -> str: + """Bot UUIDを取得する""" + +# 使用例 +bot_uuid = await event_context.get_bot_uuid() +``` + +### リクエスト変数の設定 + +単一のリクエスト内の一部の情報は、リクエスト変数に保存されます。Difyなどの外部LLMOpsプラットフォームを使用する場合、[これらの変数はLLMOpsプラットフォームに明示的に渡されます](/en/deploy/pipelines/readme.html#request-variables)。 + +```python +async def set_query_var(self, key: str, value: Any): + """クエリ変数を設定する""" + +# 使用例 +await event_context.set_query_var("key", "value") +``` + +### リクエスト変数の取得 + +単一のリクエスト変数を取得します。 + +```python +async def get_query_var(self, key: str) -> Any: + """クエリ変数を取得する""" + +# 使用例 +query_var = await event_context.get_query_var("key") +``` + +### すべてのリクエスト変数の取得 + +```python +async def get_query_vars(self) -> dict[str, Any]: + """すべてのクエリ変数を取得する""" + +# 使用例 +query_vars = await event_context.get_query_vars() +``` + +## LangBot API + +これらのAPIは、任意のプラグインコンポーネントで呼び出すことができます。アクセス方法: + +- プラグインルートディレクトリの`main.py`内: `self`オブジェクトの内部メソッド。これらのAPIはすべて、プラグインクラスの親クラス`BasePlugin`によって提供されます。 +- 任意のプラグインコンポーネントクラス内: `self.plugin`オブジェクトの内部メソッド。 + +### プラグイン設定の取得 + +プラグイン設定フォーマットは`manifest.yaml`に記述でき、ユーザーはLangBotのプラグイン管理でプラグイン設定フォーマットに従って入力する必要があります。プラグインコードはこのAPIを呼び出してプラグイン設定情報を取得できます。 + +```python +def get_config(self) -> dict[str, typing.Any]: + """プラグインの設定を取得する。""" + +# 使用例 +config = self.plugin.get_config() +``` + +### LangBotバージョンの取得 + +LangBotのバージョン番号を取得します。`v..`形式の文字列として返されます。 + +```python +async def get_langbot_version(self) -> str: + """LangBotバージョンを取得する""" + +# 使用例 +langbot_version = await self.plugin.get_langbot_version() +``` + +### 設定済みBotリストの取得 + +すべてのBot UUIDのリストを返します。 + +```python +async def get_bots(self) -> list[str]: + """すべてのBotを取得する""" + +# 使用例 +bots = await self.plugin.get_bots() +``` + +### Bot情報の取得 + +Bot情報を取得します。 + +```python +async def get_bot_info(self, bot_uuid: str) -> dict[str, Any]: + """Bot情報を取得する""" + +# 使用例 +bot_info = await self.plugin.get_bot_info("de639861-be05-4018-859b-c2e2d3e0d603") + +# 返り値の例 +{ + "uuid": "de639861-be05-4018-859b-c2e2d3e0d603", + "name": "aiocqhttp", + "description": "Migrated from LangBot v3", + "adapter": "aiocqhttp", + "enable": true, + "use_pipeline_name": "ChatPipeline", + "use_pipeline_uuid": "c30a1dca-e91c-452b-83ec-84d635a30028", + "created_at": "2025-05-10T13:53:08", + "updated_at": "2025-08-12T11:27:30", + "adapter_runtime_values": { # Botが現在実行中の場合に存在 + "bot_account_id": 960164003 # BotアカウントID + } +} +``` + +### プロアクティブメッセージの送信 + +Bot UUIDとターゲットセッションIDを通じてプロアクティブメッセージを送信します。 + +メッセージチェーンの構築方法については、[メッセージプラットフォームエンティティ](/en/plugin/dev/apis/messages)を参照してください。 + +```python +async def send_message( + self, + bot_uuid: str, + target_type: str, + target_id: str, + message_chain: platform_message.MessageChain, +) -> None: + """セッションにメッセージを送信する""" + +# 使用例 +await self.plugin.send_message( + bot_uuid="de639861-be05-4018-859b-c2e2d3e0d603", + target_type="person", + target_id="1010553892", + message_chain=platform_message.MessageChain([platform_message.Plain(text="Hello, world!")]), +) +``` + +### 設定済みLLMモデルリストの取得 + +設定されたすべてのLLMモデルのUUIDのリストを返します。 + +```python +async def get_llm_models(self) -> list[str]: + """すべてのLLMモデルを取得する""" + +# 使用例 +llm_models = await self.plugin.get_llm_models() +``` + +### LLMモデルの呼び出し + +LLMモデルを呼び出し、LLMメッセージを返します。非ストリーミング。 + +```python +async def invoke_llm( + self, + llm_model_uuid: str, + messages: list[provider_message.Message], + funcs: list[resource_tool.LLMTool] = [], + extra_args: dict[str, Any] = {}, +) -> provider_message.Message: + """LLMモデルを呼び出す""" + +# 使用例 +llm_message = await self.plugin.invoke_llm( + llm_model_uuid="llm_model_uuid", + messages=[provider_message.Message(role="user", content="Hello, world!")], + funcs=[], + extra_args={}, +) +``` + +### プラグイン永続データの設定 + +プラグインデータを永続的に保存します。このインターフェースを通じて保存されたデータは、このプラグインのみがアクセスできます。値は手動でbytesに変換する必要があります。 + +```python +async def set_plugin_storage(self, key: str, value: bytes) -> None: + """プラグインストレージ値を設定する""" + +# 使用例 +await self.plugin.set_plugin_storage("key", b"value") +``` + +### プラグイン永続データの取得 + +```python +async def get_plugin_storage(self, key: str) -> bytes: + """プラグインストレージ値を取得する""" + +# 使用例 +plugin_storage = await self.plugin.get_plugin_storage("key") +``` + +### すべてのプラグイン永続データキーの取得 + +```python +async def get_plugin_storage_keys(self) -> list[str]: + """すべてのプラグインストレージキーを取得する""" + +# 使用例 +plugin_storage_keys = await self.plugin.get_plugin_storage_keys() +``` + +### プラグイン永続データの削除 + +```python +async def delete_plugin_storage(self, key: str) -> None: + """プラグインストレージ値を削除する""" + +# 使用例 +await self.plugin.delete_plugin_storage("key") +``` + +### ワークスペース永続データの取得 + +このインターフェースを通じて保存されたデータは、すべてのプラグインがアクセスできます。値は手動でbytesに変換する必要があります。 + +```python +async def set_workspace_storage(self, key: str, value: bytes) -> None: + """ワークスペースストレージ値を設定する""" + +# 使用例 +await self.plugin.set_workspace_storage("key", b"value") +``` + +### ワークスペース永続データの取得 + +```python +async def get_workspace_storage(self, key: str) -> bytes: + """ワークスペースストレージ値を取得する""" + +# 使用例 +workspace_storage = await self.plugin.get_workspace_storage("key") +``` + +### すべてのワークスペース永続データキーの取得 + +```python +async def get_workspace_storage_keys(self) -> list[str]: + """すべてのワークスペースストレージキーを取得する""" + +# 使用例 +workspace_storage_keys = await self.plugin.get_workspace_storage_keys() +``` + +### ワークスペース永続データの削除 + +```python +async def delete_workspace_storage(self, key: str) -> None: + """ワークスペースストレージ値を削除する""" + +# 使用例 +await self.plugin.delete_workspace_storage("key") +``` + +### プラグインファイル型設定フィールドデータの取得 + +```python +async def get_config_file(self, file_key: str) -> bytes: + """設定ファイル値を取得する""" + +# 使用例 +file_bytes = await self.plugin.get_config_file("key") +``` + +これは[`file`または`array[file`](/en/plugin/dev/basic-info.html#type-file)型の設定フィールドと組み合わせて使用します。 diff --git a/docs/ja/plugin/dev/apis/messages.md b/docs/ja/plugin/dev/apis/messages.md new file mode 100644 index 000000000..972c26eda --- /dev/null +++ b/docs/ja/plugin/dev/apis/messages.md @@ -0,0 +1,96 @@ +# メッセージプラットフォームエンティティ + +:::info 目次 +[[toc]] +::: + +LangBotは複数のメッセージングプラットフォームをサポートしており、各プラットフォームには異なる`メッセージエンティティ`フォーマットがあります。これらの違いを抽象化するために、統一された標準を実装しました。プラグイン開発者は、プラグイン内でこのページに記載されているメッセージエンティティを習得して使用するだけで、LangBotの内部メッセージ処理ロジックがメッセージの解析と変換を自動的に処理します。 + +## メッセージチェーン + +メッセージングプラットフォーム上の`メッセージ`は、AI対話に使用されるメッセージとは異なります。メッセージングプラットフォーム上のメッセージは、`メッセージチェーン`の形式で記述されます。QQに表示される各独立したメッセージはメッセージチェーンであり、`テキスト`、`画像`、`@メンション`などのさまざまな`メッセージチェーンコンポーネント`を含むことができます。例えば: + +![](/assets/image/zh/plugin/dev/apis/plugin_dev_messages_01.png) + +これは、1つのPlainコンポーネント(Hello World)と1つのImageコンポーネント(Usagi)を含むメッセージチェーンです。 + +メッセージチェーンとメッセージチェーンコンポーネントの定義は、`langbot_plugin.api.entities.platform.message`にあります。 + +### メッセージチェーンの構築 + +まず、`langbot_plugin.api.entities.platform.message`パッケージをインポートして、その中のメッセージコンポーネントを使用してください。 + +```python +from langbot_plugin.api.entities.platform.message import * + +# テキスト「Hello LangBot」と画像(URLから)を含むメッセージを構築 +msg_chain = MessageChain([ + Plain(text="Hello LangBot"), + Image(url='https://qchatgpt.rockchin.top/langbot-logo.png') +]) + +# @全員とテキスト「Hello LangBot」を含むメッセージを構築 +msg_chain = MessageChain([ + AtAll(), + Plain(text="Hello LangBot") +]) + +# @特定のメンバーとテキスト「Hello LangBot」を含むメッセージを構築 +msg_chain = MessageChain([ + At(target=123456), + Plain(text="Hello LangBot") +]) +``` + +現在サポートされているメッセージチェーンコンポーネント: + +- `Source` - ソースメッセージチェーン情報。メッセージングプラットフォームから受信したメッセージには、メッセージ情報を記録するためにメッセージチェーンの先頭にこのコンポーネントが含まれます +- `Plain` - プレーンテキストメッセージ +- `Quote` - 引用メッセージ +- `Image` - 画像メッセージ +- `AtAll` - @全員メッセージ +- `At` - @特定のメンバーメッセージ +- `Voice` - 音声メッセージ + - メッセージングプラットフォームのサポートを確認する必要があります +- `Forward` - 転送メッセージ + - 多くのプラットフォームでサポートされていないため、推奨されません +- `File` - ファイルメッセージ + +コンポーネントを作成する際は、名前付きパラメータを使用する必要があります。具体的な使用方法については、ソースコード`langbot_plugin.api.entities.platform.message`の定義を確認してください。 + +## その他のエンティティ + +上記のエンティティに加えて、`Friend`や`Group`などのエンティティもあります。これらのエンティティは`langbot_plugin.api.entities.platform.entities`で定義されています。 + +## 基盤プラットフォームAPIへのアクセス + +:::warning 注意 +4.xには適用されません。 +::: + +プラットフォームの違いを抽象化するために、LangBotはメッセージングプラットフォームAPIの上に抽象化レイヤーを提供しています。これには、上記で説明した内容と、`pkg/platform/sources`ディレクトリ内のさまざまなプラットフォームアダプターが含まれます。 +ただし、プラットフォームの違いが大きいため、抽象化レイヤーのエンティティとAPIのカプセル化は完全ではありません。プラグインがプラットフォーム固有の機能にアクセスする必要がある場合は、次の手順に従って基盤APIにアクセスできます。 + +:::info +ここでの`adapter`は、各アダプターのインスタンス化されたオブジェクトであり、`pkg/platform/sources/`以下のファイル内の`xxxAdapter(adapter.MessagePlatformAdapter)`クラスに対応します。プラグインイベントの`query.adapter`から取得できます。例えば: + +```python + # 例えばプラグイン内で + @handler(GroupMessageReceived) + async def _(self, ctx: EventContext): + # アダプターオブジェクトを取得 + adapter = ctx.query.adapter +``` +::: + +| プラットフォーム | アダプター | アクセス方法 | 説明 | +| --- | --- | --- | --- | +| OneBot v11| aiocqhttp | adapter.bot | botオブジェクトは[aiocqhttp](https://github.com/nonebot/aiocqhttp) CQHttpオブジェクトに対応します。詳細な使用方法についてはaiocqhttpドキュメントを参照してください | +| QQ公式API | qqofficial | adapter.bot | botオブジェクトはlibs/qq_official_api以下のSDKオブジェクトです。詳細な使用方法については、libs/qq_official_api/api.pyの`QQOfficialClient`内の`send_group_text_msg`メソッドを参照してHTTPリクエストメソッドを確認し、具体的なインターフェースドキュメントについてはQQ公式APIドキュメントを参照してください | +| WeCom(企業微信) | wecom | adapter.bot | libs/wecom_api/api.pyの`WecomClient`内の`send_image`メソッドを参照してHTTPリクエストメソッドを確認し、具体的なインターフェースドキュメントについてはWeCom APIドキュメントを参照してください | +| WeChat公式アカウント | officialaccount | - | インターフェースドキュメントについてはWeChat公式アカウントAPIドキュメントを参照してください。認証情報はadapter.botから取得できます | +| Lark | lark | adapter.api_client | Lark SDKのAPI Clientオブジェクトです。詳細については[oapi-sdk-python](https://github.com/larksuite/oapi-sdk-python)を参照してください | +| DingTalk | dingtalk | - | DingTalk APIドキュメントを参照してください。認証情報はadapter.botから取得できます | +| Discord | discord | adapter.bot | botオブジェクトは[Rapptz/discord.py](https://github.com/Rapptz/discord.py) Discordオブジェクトです。詳細な使用方法についてはドキュメントを参照してください | +| Telegram | telegram | adapter.bot | botオブジェクトは[python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) Telegramオブジェクトです。詳細な使用方法についてはドキュメントを参照してください | +| Slack | slack | adapter.bot | botオブジェクトはlibs/slack_api/api.py内にあります。詳細な使用方法についてはそのコードとSlack SDKを参照してください | diff --git a/docs/ja/plugin/dev/apis/pipeline-events.md b/docs/ja/plugin/dev/apis/pipeline-events.md new file mode 100644 index 000000000..fed0ece16 --- /dev/null +++ b/docs/ja/plugin/dev/apis/pipeline-events.md @@ -0,0 +1,293 @@ +# パイプラインイベントとAPI + +:::info 目次 +[[toc]] +::: + +LangBotプラグインはパイプラインイベントを登録して処理できます。使用方法については、[コンポーネント: イベントリスナー](/en/plugin/dev/components/event-listener)を参照してください。 + +## イベント一覧 + +一部のイベントには`設定可能な属性`があり、プラグインコードで変更して、その後のLangBot処理で使用できます。 + +### *MessageReceived + +グループチャットまたはプライベートチャットでメッセージを受信したときにトリガーされます。 + +```python +class PersonMessageReceived(BaseEventModel): + """プライベートチャットメッセージを受信したとき""" + + event_name: str = "PersonMessageReceived" + + launcher_type: str + """起動元オブジェクトタイプ(person)""" + + launcher_id: typing.Union[int, str] + """送信者ID""" + + sender_id: typing.Union[int, str] + """送信者ID""" + + message_chain: platform_message.MessageChain = pydantic.Field( + serialization_alias="message_chain" + ) + """生のメッセージチェーン""" + +class GroupMessageReceived(BaseEventModel): + """グループチャットメッセージを受信したとき""" + + event_name: str = "GroupMessageReceived" + + launcher_type: str + """起動元オブジェクトタイプ(group)""" + + launcher_id: typing.Union[int, str] + """グループID""" + + sender_id: typing.Union[int, str] + """送信者ID""" + + message_chain: platform_message.MessageChain = pydantic.Field( + serialization_alias="message_chain" + ) + """生のメッセージチェーン""" +``` + +### *NormalMessageReceived + +グループチャットまたはプライベートチャットメッセージを受信し、LLMで処理する必要があるメッセージ(コマンドでないメッセージ)であると判定されたときにトリガーされます。 + +```python +class PersonNormalMessageReceived(BaseEventModel): + """処理すべきプライベートチャット通常メッセージが判定されたときにトリガーされる""" + + event_name: str = "PersonNormalMessageReceived" + + launcher_type: str + + launcher_id: typing.Union[int, str] + + sender_id: typing.Union[int, str] + + text_message: str + """メッセージテキスト""" + + message_chain: platform_message.MessageChain = pydantic.Field( + serialization_alias="message_chain" + ) + """生のメッセージチェーン""" + + # ========== 設定可能な属性 ========== + + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """変更されたメッセージテキスト、langbot_plugin.api.entities.builtin.provider.message.ContentElement型""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """返信メッセージコンポーネントリスト、デフォルト動作を防止した場合のみ有効""" + +class GroupNormalMessageReceived(BaseEventModel): + """処理すべきグループチャット通常メッセージが判定されたときにトリガーされる""" + + event_name: str = "GroupNormalMessageReceived" + + launcher_type: str + + launcher_id: typing.Union[int, str] + + sender_id: typing.Union[int, str] + + text_message: str + """メッセージテキスト""" + + message_chain: platform_message.MessageChain = pydantic.Field( + serialization_alias="message_chain" + ) + """生のメッセージチェーン""" + + # ========== 設定可能な属性 ========== + + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """変更されたメッセージテキスト、langbot_plugin.api.entities.builtin.provider.message.ContentElement型""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """返信メッセージコンポーネントリスト、デフォルト動作を防止した場合のみ有効""" +``` + +### *CommandSent + +:::warning 注意 +使用は推奨されなくなりました。代わりに[コンポーネント: Command](/en/plugin/dev/components/command)を使用してください。 +::: + +グループチャットまたはプライベートチャットでコマンドを受信したときにトリガーされます。 + +```python +class PersonCommandSent(BaseEventModel): + """処理すべきプライベートチャットコマンドが判定されたときにトリガーされる""" + + event_name: str = "PersonCommandSent" + + launcher_type: str + + launcher_id: typing.Union[int, str] + + sender_id: typing.Union[int, str] + + command: str + """コマンドテキスト""" + + params: list[str] + """コマンドパラメータ""" + + text_message: str + """メッセージテキスト""" + + is_admin: bool + """管理者かどうか""" + + +class GroupCommandSent(BaseEventModel): + """処理すべきグループチャットコマンドが判定されたときにトリガーされる""" + + event_name: str = "GroupCommandSent" + + launcher_type: str + + launcher_id: typing.Union[int, str] + + sender_id: typing.Union[int, str] + + command: str + """コマンドテキスト""" + + params: list[str] + """コマンドパラメータ""" + + text_message: str + """メッセージテキスト""" + + is_admin: bool + """管理者かどうか""" + +``` + +### NormalMessageResponded + +メッセージがLLMレスポンスを受信したときにトリガーされます。 + +```python +class NormalMessageResponded(BaseEventModel): + """通常メッセージに返信するときにトリガーされる""" + + event_name: str = "NormalMessageResponded" + + launcher_type: str + + launcher_id: typing.Union[int, str] + + sender_id: typing.Union[int, str] + + session: provider_session.Session + """セッションオブジェクト""" + + prefix: str + """返信メッセージプレフィックス""" + + response_text: str + """返信メッセージテキスト""" + + finish_reason: str + """レスポンス終了理由""" + + funcs_called: list[str] + """呼び出された関数のリスト""" + + # ========== 設定可能な属性 ========== + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """返信メッセージコンポーネントリスト、デフォルト動作を防止した場合のみ有効""" +``` + +### PromptPreProcessing + +LLMレスポンスコンテキスト(プロンプト)を構築するときにトリガーされます。 + +```python +class PromptPreProcessing(BaseEventModel): + """セッション内のプロンプトを前処理するときにトリガーされる""" + + event_name: str = "PromptPreProcessing" + + session_name: str + + # ========== 設定可能な属性 ========== + + default_prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]] + """この会話のシナリオプリセット、変更可能、langbot_plugin.api.entities.builtin.provider.message.Messageまたはlangbot_plugin.api.entities.builtin.provider.message.MessageChunk型""" + + prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]] + """この会話の既存メッセージレコード、変更可能、langbot_plugin.api.entities.builtin.provider.message.Messageまたはlangbot_plugin.api.entities.builtin.provider.message.MessageChunk型""" +``` + +## イベントコンテキストAPI + +```python +... + @self.handler(events.PersonMessageReceived) + async def handler(event_context: context.EventContext): + ... +``` + +イベント処理メソッドには`EventContext`オブジェクトが渡され、イベントコンテキスト情報が含まれます。このオブジェクトには[リクエストAPI](/en/plugin/dev/apis/common)とイベントコンテキスト固有のAPIの両方があります。以下は、イベントコンテキスト固有のAPIのリストです: + +### 元のイベント属性の取得 + +`event_context.event`属性は元のイベントオブジェクトであり、元のイベントの属性を取得できます。型はリッスンされているイベントの型です。 + +例えば、リッスンされているイベントが`GroupMessageReceived`の場合: + +```python +event = event_context.event +print(event.launcher_type) # 起動元オブジェクトタイプ(group) +print(event.launcher_id) # グループID +print(event.sender_id) # 送信者アカウントID +print(event.message_chain) # メッセージチェーン +``` + +### デフォルト動作を防止 + +```python +def prevent_default(self): + """デフォルト動作を防止する""" + +# 使用例 +event_context.prevent_default() +``` + +このメソッドを呼び出すと、このイベントのデフォルトの後続動作が防止され、パイプラインは直接終了します。 + +:::info +次のイベントのみがデフォルト動作を防止できます: + +- PersonMessageReceived +- GroupMessageReceived +- PersonNormalMessageReceived +- GroupNormalMessageReceived +- PersonCommandSent +- GroupCommandSent +- NormalMessageResponded + +::: + +### 後続実行を防止 + +```python +def prevent_postorder(self): + """後続実行を防止する""" + +# 使用例 +event_context.prevent_postorder() +``` + +このメソッドを呼び出すと、後続のプラグインがこの時点で実行されなくなります。 diff --git a/docs/ja/plugin/dev/apis/tech-details.md b/docs/ja/plugin/dev/apis/tech-details.md new file mode 100644 index 000000000..1036f5f38 --- /dev/null +++ b/docs/ja/plugin/dev/apis/tech-details.md @@ -0,0 +1,11 @@ +# プラグイン技術詳細 + +## アーキテクチャ + + + +バージョン4.0では、高セキュリティで柔軟性の高い本番環境グレードのプラグインシステムを導入し、開発者に豊富なAPIと使いやすいサポートツールを提供しています。 + +Plugin Runtimeは、プラグインのライフサイクルを管理し、LangBotとプラグイン間の相互作用を調整するために使用されます。`stdio`と`websocket`の2つの動作モードがあります。LangBotがユーザーによって直接起動される場合(コンテナ内で実行されていない場合)、`stdio`モードを使用します。これは個人ユーザーや軽量環境で一般的です。LangBotがコンテナ内で実行される場合、`websocket`モードを使用します。これは本番環境専用に設計されています。 + +Plugin Runtimeは、インストールされた各プラグインを自動的に起動し、stdioを通じて相互作用します。プラグイン開発シナリオでは、開発者は`lbp`コマンドラインツールを使用してプラグインを起動し、WebSocketを介して実行中のRuntimeに接続してデバッグできます。 diff --git a/docs/ja/plugin/dev/basic-info.md b/docs/ja/plugin/dev/basic-info.md new file mode 100644 index 000000000..42d31e7f5 --- /dev/null +++ b/docs/ja/plugin/dev/basic-info.md @@ -0,0 +1,244 @@ +# プラグイン設定情報の完成 + +:::info 目次 +[[toc]] +::: + +## マニフェストファイルの修正 + +プラグインディレクトリ内の`manifest.yaml`ファイルは、プラグインの基本情報を宣言します。これはLangBot UIまたはプラグインマーケットプレイスのインターフェースに表示されます。 + +```yaml +apiVersion: v1 # 変更しないでください +kind: Plugin # 変更しないでください +metadata: + author: RockChinQ # 作成者、正規表現^[a-zA-Z0-9_-]+$に一致する必要があります + name: HelloPlugin # プラグイン名、プラグインを区別するために使用、正規表現^[a-zA-Z0-9-]+$に一致する必要があります + repository: 'https://github.com/langbot-app/HelloPlugin' # プラグインリポジトリURL + version: 0.1.0 # プラグインバージョン + description: + en_US: 'Hello LangBot Plugin' # プラグイン説明、多言語対応 + zh_Hans: 'Hello LangBot Plugin' + label: + en_US: HelloPlugin # プラグインラベル、インターフェースに表示、多言語対応 + zh_Hans: HelloPlugin + icon: assets/icon.svg # プラグインアイコン、デフォルトはassets/icon.svg、さまざまな画像形式に置き換え可能 +spec: + config: [] # プラグイン設定項目フォーマット + components: {} # プラグインコンポーネントリスト、手動で変更する必要はありません +execution: + python: + path: main.py # 変更しないでください + attr: HelloPlugin # 変更しないでください +``` + +プラグインの多言語サポートは[RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646)標準に従います。現在サポートされている言語は次のとおりです: + +- `en_US` 英語 +- `zh_Hans` 簡体字中国語 +- `zh_Hant` 繁体字中国語 +- `ja_JP` 日本語 + +## プラグイン設定項目フォーマット + +`manifest.yaml`ファイルの`spec.config`で宣言されたフィールドは、LangBotによってユーザーが入力するための設定項目フォームとしてレンダリングされます。プラグインは、SDKが提供するAPIを通じて、ユーザーが入力した設定項目を取得できます(後のセクションを参照)。 + +例えば: + +```yaml +spec: + config: + - name: github_token # 必須; 設定項目名、プラグイン内での取得に使用 + type: string # 必須; 設定項目タイプ、string、integer、float、boolean、select、prompt-editor、llm-model-selector、bot-selectorなどをサポート + label: # 必須; 設定項目表示名、多言語サポート。言語コードはRFC 4646標準に従います。 + en_US: Github Token + zh_Hans: Github Token + description: # 設定項目説明、多言語サポート。オプション。 + en_US: Image downloading requires a Github token + zh_Hans: 如果不填的話、图片可能會下載失败 + default: '' # 設定項目のデフォルト値、オプション。 + required: false # 設定項目が必須かどうか、オプション。 + - name: mode + type: select + ... +``` + +設定項目でサポートされるタイプとフィールドは次のとおりです: + +### type: string + +文字列型。 + +```yaml +- name: api_key + type: string + ... +``` + +### type: array[string] + +文字列配列。 + +```yaml +- name: tags + type: array[string] + ... +``` + +### type: integer + +整数型。 + +```yaml +- name: progress + type: integer + ... +``` + +### type: float + +浮動小数点型。 + +```yaml +- name: temperature + type: float + ... +``` + +### type: boolean + +ブール型。 + +```yaml +- name: is_enabled + type: boolean + ... +``` + +### type: select + +ドロップダウンメニュー。`options`の設定が必要で、ドロップダウンメニューのオプションを表します。 + +```yaml +- name: mode + type: select + options: # ドロップダウンオプション、多言語サポート。 + - name: mode1 # 値 + label: # 表示名、多言語サポート。 + en_US: Mode 1 + zh_Hans: 模式 1 + - name: mode2 + label: # 表示名、多言語サポート。 + en_US: Mode 2 + zh_Hans: 模式 2 + ... +``` + +### type: prompt-editor + +プロンプトエディター。パイプライン設定ページからプロンプトエディターを表示し、最終結果はOpenAIの`messages`形式で表されます。 + +```yaml +- name: prompt + type: prompt-editor + ... +``` + +### type: text + +大きなテキスト入力。フロントエンドでtextareaとしてレンダリングされ、ユーザーが入力し、文字列としてプラグインに渡されます。 + +```yaml +- name: prompt + type: text + ... +``` + +### type: file + +ファイルアップロード。最大10MBのファイルアップロードをサポートし、`{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}`形式でプラグインに渡されます。プラグインは`get_config_file` APIを使用してファイルの内容を取得できます。 + +```yaml +- name: config_file + type: file + accept: 'application/json' # オプション、受け入れるファイルMIMEタイプを指定 + ... +``` + +プラグインでファイルを取得する: + +```python +# 設定からファイル情報を取得 +file_config = self.get_config()['config_file'] +file_key = file_config['file_key'] +mimetype = file_config['mimetype'] + +# 出力例: {'file_input': {'file_key': 'plugin_config_d2234fd802054faf80babe0679a97fa9.json', 'mimetype': 'application/json'}} +print(file_config) + +# ファイルの内容を取得 +file_bytes = await self.get_config_file(file_key) +``` + +::: info +一般的なMIMEタイプとファイル拡張子のリファレンス: [MDNドキュメント](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) +::: + +### type: array[file] + +複数ファイルアップロード。fileタイプと似ていますが、複数のファイルのアップロードをサポートし、`[{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}]`形式でプラグインに渡されます。 + +```yaml +- name: resource_files + type: array[file] + accept: 'image/*' # オプション、受け入れるファイルMIMEタイプを指定 + ... +``` + +プラグインでファイルを取得する: + +```python +# 設定からファイルリストを取得 +files_config = self.get_config()['resource_files'] + +for file_config in files_config: + file_key = file_config['file_key'] + mimetype = file_config['mimetype'] + + # ファイルの内容を取得 + file_bytes = await self.get_config_file(file_key) +``` + +### type: llm-model-selector + +LLMモデルセレクター。設定されたLLMモデルを選択できるLLMモデルセレクターを表示し、最終結果はLLMモデルUUIDとして表されます。 + +```yaml +- name: model + type: llm-model-selector + ... +``` + +### type: bot-selector + +Botセレクター。設定されたBotを選択できるBotセレクターを表示し、最終結果はBot UUIDとして表されます。 + +```yaml +- name: bot + type: bot-selector + ... +``` + +プラグインでBot UUIDを使用する: + +```python +# 設定からBot UUIDを取得 +bot_uuid = self.get_config()['bot'] +print(bot_uuid) # 出力: '550e8400-e29b-41d4-a716-446655440000' +``` + +## 次のステップ + +このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。 + +- コンポーネントの追加: プラグインコンポーネントはプラグインのコア機能ユニットです。必要に応じて[コンポーネントを追加](/en/plugin/dev/components/add)できます。 diff --git a/docs/ja/plugin/dev/components/add.md b/docs/ja/plugin/dev/components/add.md new file mode 100644 index 000000000..598ff1b51 --- /dev/null +++ b/docs/ja/plugin/dev/components/add.md @@ -0,0 +1,73 @@ +# コンポーネントの追加 + +プラグインは、LangBotにさまざまな機能を提供する1つ以上のコンポーネントで構成されています。現在サポートされているコンポーネントタイプには次のものがあります: + +- イベントリスナー(EventListener): パイプライン実行中のイベントをリッスンし、コンテキストやパイプラインを変更します。 +- コマンド(Command): `!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。 +- ツール(Tool): LangBotの組み込みLocal Agentの実行中にLLMによって呼び出されます。 +- ナレッジリトリーバー(KnowledgeRetriever): LangBotに外部ナレッジベース検索機能を提供し、さまざまなRAGシステムとの統合をサポートします。 + +## コンポーネントの追加 + +プラグインディレクトリでコマンドを実行します: + +```bash +lbp comp +``` + +例えば、イベントリスナーを追加する場合: + +```bash +lbp comp EventListener +``` + +プロンプトに従って、コンポーネント設定(ある場合)を入力します。 + +```bash +➜ HelloPlugin > lbp comp EventListener +Generating component EventListener... +Component EventListener generated successfully. +組件 EventListener 生成成功。 +➜ HelloPlugin > +``` + +:::info +CLIはプラグインディレクトリに`components`ディレクトリを生成し、その中に対応するコンポーネントディレクトリを作成します。 + +``` +. +├── assets +│ └── icon.svg +├── components +│ ├── __init__.py +│ └── event_listener +│ ├── __init__.py +│ ├── default.py +│ └── default.yaml +├── main.py +├── manifest.yaml +├── README.md +└── requirements.txt +``` + +同時に、プラグインの`manifest.yaml`にコンポーネント検出設定が追加されます: + +```yaml +... +components: + EventListener: + fromDirs: + - path: components/event_listener/ +... +``` +コンポーネントを削除するには、対応する情報を手動で削除できます。 +::: + +## コンポーネントタイプ + +各コンポーネントの詳細な使用方法については、次を参照してください: + +- [EventListener](./event-listener.md) +- [Command](./command.md) +- [Tool](./tool.md) +- [KnowledgeRetriever](./knowledge-retriever.md) diff --git a/docs/ja/plugin/dev/components/command.md b/docs/ja/plugin/dev/components/command.md new file mode 100644 index 000000000..5ddf5e9dd --- /dev/null +++ b/docs/ja/plugin/dev/components/command.md @@ -0,0 +1,212 @@ +# コンポーネント: Command + +Commandコンポーネントは、`!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。`!help`コマンドをトリガーする例を次に示します: + + + +## Commandコンポーネントの追加 + +1つのプラグインには任意の数のコマンドを含めることができます。プラグインディレクトリでコマンド`lbp comp Command`を実行し、プロンプトに従ってコマンド設定を入力します。 + +```bash +➜ HelloPlugin > lbp comp Command +Generating component Command... +Command name: info +Command description: Show information of the query +Component Command generated successfully. +組件 Command 生成成功。 +``` + +これにより、`components/commands/`ディレクトリに`info.yaml`と`info.py`ファイルが生成されます。`.yaml`ファイルは`!info`コマンドの基本情報を定義し、`.py`ファイルはコマンドハンドラです: + +```bash +➜ HelloPlugin > tree +... +├── components +│ ├── __init__.py +│ ├── commands +│ │ ├── __init__.py +│ │ ├── info.py +│ │ └── info.yaml +... +``` + +## マニフェストファイル: Commandコンポーネント + +```yaml +apiVersion: v1 # 変更しないでください +kind: Command # 変更しないでください +metadata: + name: info # コマンド名、ユーザーは!infoでこのコマンドをトリガーします + label: # コマンド表示名、LangBot UIに表示、多言語対応 + en_US: Info + zh_Hans: Info + description: # コマンド説明、LangBot UIに表示、多言語対応。オプション。 + en_US: 'Show information of the query' + zh_Hans: '発送此次消息的詳細信息' +spec: +execution: + python: + path: info.py # コマンドハンドラ、変更しないでください + attr: Info # コマンドハンドラクラス名、info.pyのクラス名と一致 +``` + +## プラグイン処理 + +以下のコードがデフォルトで生成されます(components/command/.py)。`Info`クラスの`initialize`メソッドでサブコマンド処理ロジックを登録して実装する必要があります。 + +```python +# Auto generated by LangBot Plugin SDK. +# Please refer to https://docs.langbot.app/en/plugin/dev/tutor.html for more details. +from __future__ import annotations + +from typing import Any, AsyncGenerator + +from langbot_plugin.api.definition.components.command.command import Command, Subcommand +from langbot_plugin.api.entities.builtin.command.context import ExecuteContext, CommandReturn + + +class Info(Command): + + async def initialize(self): + await super().initialize() + + "Fill with your code here" +``` + +サブコマンドの追加: + +```python +... +class Info(Command): + + async def initialize(self): + await super().initialize() + + @self.subcommand( + name="", # 空文字列はルートコマンドを表す + help="Show information of the query", # コマンドヘルプ情報 + usage="info", # コマンド使用例、コマンドヘルプに表示 + aliases=["i"], # コマンドエイリアス + ) + async def send(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]: + print(context) + + reply_text = f"Query ID: {context.query_id}\n" + reply_text += f"command: {context.command}\n" + reply_text += f"command_text: {context.command_text}\n" + reply_text += f"params: {context.params}\n" + reply_text += f"crt_params: {context.crt_params}\n" + reply_text += f"privilege: {context.privilege}\n" + reply_text += f"session: {context.session.launcher_type.value}_{context.session.launcher_id}\n" + + yield CommandReturn( + text=reply_text, + ) + + @self.subcommand( + name="field", + help="Show information of the field", + usage="info field", + aliases=["f"], + ) + async def field(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]: + print(context) + + field_name = context.crt_params[0] + field_value = getattr(context, field_name) + + yield CommandReturn( + text=f"{field_name}: {field_value}", + ) +``` + +このコードでは、`@self.subcommand`デコレータを通じて`send`関数がサブコマンドとして登録され、コマンドコンテキスト(ExecuteContext)情報を出力し、それを返信メッセージに連結します。 + +### サブコマンド登録 + +`name`はサブコマンド名です。空のままにすると、メインコマンドを処理することを意味します。空でない場合、2番目のパラメータをコマンドとして照合します。例えば: + +- `!info`は、name=""のサブコマンドに一致 +- `!info field`は、name="field"のサブコマンドに一致 +- `!info field value`は、name="field"のサブコマンドに一致し、`value`がサブコマンドパラメータ +- 特に、`name="*"`は、一致しないすべての第1レベルサブコマンドに一致し、`info`の後の各セクションをパラメータとして渡します。例えば`!info 123`、`!info abc`。ユーザーの入力に応じて、`context.crt_params`から`['123']`または`['abc']`を取得できます。 + +サブコマンド関数では、`context`変数を通じてコマンドパラメータを読み取ることができます。 + +上記のコマンドの効果は画像に示されています: + + + +### コマンドコンテキスト + +```python + +class ExecuteContext(pydantic.BaseModel): + """単一コマンド実行コンテキスト""" + + query_id: int + """リクエストID""" + + session: provider_session.Session + """このメッセージのセッションオブジェクト""" + + command_text: str + """完全なコマンドテキスト""" + + command: str + """コマンド名""" + + crt_command: str + """現在のコマンド + + マルチレベルコマンドでは、crt_commandは現在のコマンド、commandはルートコマンド。 + 例: !plugin on Webwlkr + pluginを処理する場合、commandはplugin、crt_commandはplugin + onを処理する場合、commandはplugin、crt_commandはon + """ + + params: list[str] + """コマンドパラメータ + + コマンド全体をスペースで分割した後のパラメータリスト + """ + + crt_params: list[str] + """現在のコマンドパラメータ + + マルチレベルコマンドでは、crt_paramsは現在のコマンドパラメータ、paramsはルートコマンドパラメータ。 + 例: !plugin on Webwlkr + pluginを処理する場合、paramsは['on', 'Webwlkr']、crt_paramsは['on', 'Webwlkr'] + onを処理する場合、paramsは['on', 'Webwlkr']、crt_paramsは['Webwlkr'] + """ + + privilege: int + """セッション権限レベル""" + + ... +``` + +### コマンド戻り値 + +コマンド戻り値(CommandReturn)は、現在テキスト、画像(image_url、画像リンク)、エラーの返却をサポートしています。 + +```python +yield CommandReturn( + text=reply_text, +) + +yield CommandReturn( + image_url=image_url, +) +``` + +コマンド処理は複数のメッセージを返すことをサポートしているため、`yield`ステートメントを使用してメッセージを返してください。 + +具体的な戻り値については、`CommandReturn`の定義を参照してください: [langbot_plugin.api.entities.builtin.command.context.CommandReturn](https://github.com/langbot-app/langbot-plugin-sdk/tree/main/src/langbot_plugin/api/entities/builtin/command/context.py) + +## 次のステップ + +コマンド登録とコマンド実行の基本情報を学びました。次は: + +- [プラグイン共通API](/en/plugin/dev/apis/common)を確認してください diff --git a/docs/ja/plugin/dev/components/event-listener.md b/docs/ja/plugin/dev/components/event-listener.md new file mode 100644 index 000000000..72c80aa9a --- /dev/null +++ b/docs/ja/plugin/dev/components/event-listener.md @@ -0,0 +1,101 @@ +# コンポーネント: イベントリスナー + +LangBotのパイプラインは実行時にイベントを生成し、プラグインがフックして処理できるようにします。各プラグインは1つのイベントリスナー(components/event_listener/default.yaml)のみを持つことができますが、その中で任意の数のイベントを登録できます。 + +## イベントリスナーコンポーネントの追加 + +プラグインディレクトリでコマンド`lbp comp EventListener`を実行します。イベントリスナーコンポーネントの作成には設定は必要ありません。 + +```bash +➜ HelloPlugin > lbp comp EventListener +Generating component EventListener... +Component EventListener generated successfully. +組件 EventListener 生成成功。 +``` + +これにより、`components/event_listener/`ディレクトリに`default.yaml`と`default.py`ファイルが生成されます。`.yaml`ファイルはイベントリスナーの基本情報を定義し、`.py`ファイルはイベントリスナーハンドラです: + +```bash +➜ HelloPlugin > tree +... +├── components +│ ├── __init__.py +│ └── event_listener +│ ├── __init__.py +│ ├── default.py +│ └── default.yaml +... +``` + +## マニフェストファイル: イベントリスナー + +各プラグインは1つのイベントリスナーのみを持つことができるため、マニフェストファイルでの変更は必要ありません。 + +## プラグイン処理 + +以下のコードがデフォルトで生成されます(components/event_listener/default.py)。`DefaultEventListener`クラスの`initialize`メソッドでイベント処理ロジックを登録して実装する必要があります。 + +```python +# Auto generated by LangBot Plugin SDK. +# Please refer to https://docs.langbot.app/en/plugin/dev/tutor.html for more details. +from __future__ import annotations + +from langbot_plugin.api.definition.components.common.event_listener import EventListener +from langbot_plugin.api.entities import events, context + + +class DefaultEventListener(EventListener): + + async def initialize(self): + await super().initialize() + + "Fill with your code here" +``` + +特定のイベントのリスナーを追加: + +```python +... +class DefaultEventListener(EventListener): + + async def initialize(self): + await super().initialize() + + @self.handler(events.PersonMessageReceived) + async def handler(event_context: context.EventContext): + print("Hello LangBot Plugin!") + print(event_context) + + await event_context.reply( + platform_message.MessageChain([ + platform_message.Plain(text=f"Hello from Nahida Plugin!"), + ]) + ) +``` + +このコードは、`PersonMessageReceived`(プライベートチャットからのメッセージを受信)イベントのリスナーを登録し、イベントがトリガーされたときにイベントコンテキスト(EventContext)情報を出力し、イベントコンテキストAPIを呼び出してメッセージで返信します。 + +EventContextはこのイベントトリガーの共通コンテキスト情報を保存し、EventContext.eventはPersonMessageReceived(または他の対応するイベントタイプ)のオブジェクトで、イベントの詳細情報を保存します。 + +```python +# EventContext定義の概要 +class EventContext(pydantic.BaseModel): + """イベントコンテキスト、このイベント実行の情報を保存""" + ... + + event: pydantic.SerializeAsAny[BaseEventModel] + """イベントオブジェクト、具体的な型はハンドラ登録時に指定された型、events.pyで見つけることができます""" + + ... +``` + +## イベント登録 + +イベント登録は`@self.handler`デコレータを通じて実装され、デコレータのパラメータはイベントタイプです。監視可能なすべてのイベントは`langbot_plugin.api.entities.builtin.events`で定義されています。 + +## 次のステップ + +イベントリスナーの基本情報を学びました。次は: + +- ドキュメント[パイプラインイベント](/en/plugin/dev/apis/pipeline-events)で`監視可能なイベントのリスト`と`イベントコンテキストAPI`を確認してください +- [プラグイン共通API](/en/plugin/dev/apis/common)を確認してください diff --git a/docs/ja/plugin/dev/components/knowledge-retriever.md b/docs/ja/plugin/dev/components/knowledge-retriever.md new file mode 100644 index 000000000..c01a88b8d --- /dev/null +++ b/docs/ja/plugin/dev/components/knowledge-retriever.md @@ -0,0 +1,264 @@ +# コンポーネント: ナレッジリトリーバー + +ナレッジリトリーバーコンポーネントにより、プラグインはLangBotに外部ナレッジベース検索機能を提供できます。ユーザーがLangBotで外部ナレッジベースを作成する際、プラグインが提供するナレッジリトリーバーを選択してナレッジを検索できます。 + + + +## ナレッジリトリーバーコンポーネントの追加 + +1つのプラグインには任意の数のナレッジリトリーバーを追加できます。プラグインディレクトリでコマンド`lbp comp KnowledgeRetriever`を実行し、プロンプトに従ってナレッジリトリーバーの設定を入力します。 + +```bash +➜ FastGPTRetriever > lbp comp KnowledgeRetriever +Generating component KnowledgeRetriever... +KnowledgeRetriever name: fastgpt +KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases +Component KnowledgeRetriever generated successfully. +``` + +これにより、`components/knowledge_retriever/`ディレクトリに`fastgpt.yaml`と`fastgpt.py`ファイルが生成されます。`.yaml`ファイルはナレッジリトリーバーの基本情報と設定パラメータを定義し、`.py`ファイルはこのリトリーバーのハンドラです: + +```bash +➜ FastGPTRetriever > tree +... +├── components +│ ├── __init__.py +│ └── knowledge_retriever +│ ├── __init__.py +│ ├── fastgpt.py +│ └── fastgpt.yaml +... +``` + +## マニフェストファイル: ナレッジリトリーバー + +```yaml +apiVersion: v1 # 変更しないでください +kind: KnowledgeRetriever # 変更しないでください +metadata: + name: fastgpt # ナレッジリトリーバー名、このリトリーバーを識別するために使用 + label: + en_US: FastGPT Knowledge Base # リトリーバー表示名、LangBotのUIに表示、多言語対応 + zh_Hans: FastGPT 知識庫 + ja_JP: FastGPT ナレッジベース + description: + en_US: 'Retrieve knowledge from FastGPT knowledge bases' # リトリーバー説明、LangBotのUIに表示、多言語対応。オプション + zh_Hans: '従 FastGPT 知識庫中検索知識' + ja_JP: 'FastGPT ナレッジベースから知識を取得' + icon: assets/icon.svg # リトリーバーアイコン、外部ナレッジベース設定ページに表示 +spec: + config: # リトリーバー設定パラメータ、ユーザーは外部ナレッジベース作成時にこれらのパラメータを入力する必要があります + - name: api_base_url # パラメータ名 + type: string # パラメータタイプ: string、number、boolean、select + label: + en_US: API Base URL + zh_Hans: API 基礎地址 + ja_JP: API ベース URL + description: + en_US: 'Base URL for FastGPT API' + zh_Hans: 'FastGPT API 基礎地址' + ja_JP: 'FastGPT API ベース URL' + default: 'http://localhost:3000' # デフォルトパラメータ値 + required: true # 必須かどうか + - name: api_key + type: string + label: + en_US: FastGPT API Key + zh_Hans: FastGPT API Key + ja_JP: FastGPT API キー + description: + en_US: 'API key from your FastGPT instance' + zh_Hans: '従您的 FastGPT 実例獲取的 API Key' + ja_JP: 'FastGPT インスタンスから取得した API Key' + default: '' + required: true + - name: search_mode # select型パラメータの例 + type: select + label: + en_US: Search Mode + zh_Hans: 搜索模式 + ja_JP: 検索モード + description: + en_US: 'The search method to use' + zh_Hans: '使用的搜索方法' + ja_JP: '使用する検索方法' + default: 'embedding' + options: # select型パラメータはオプションリストを定義する必要があります + - name: 'embedding' + label: + en_US: 'Embedding Search' + zh_Hans: '向量搜索' + ja_JP: '埋め込み検索' + - name: 'fullTextRecall' + label: + en_US: 'Full-Text Recall' + zh_Hans: '全文検索' + ja_JP: '全文検索' + - name: using_rerank # boolean型パラメータの例 + type: boolean + label: + en_US: Use Re-ranking + zh_Hans: 使用重排序 + ja_JP: リランキングを使用 + description: + en_US: 'Whether to use re-ranking' + zh_Hans: '是否使用重排序' + ja_JP: 'リランキングを使用するかどうか' + default: false + required: false +execution: + python: + path: fastgpt.py # リトリーバーハンドラ、変更しないでください + attr: FastGPT # リトリーバーハンドラのクラス名、fastgpt.pyのクラス名と一致 +``` + +設定項目フォーマットのリファレンスについては、[プラグインマニフェスト設定フォーマット](/en/plugin/dev/basic-info)を参照してください。 + +## プラグインハンドラ + +以下のコードがデフォルトで生成されます(components/knowledge_retriever/.py)。`FastGPT`クラスの`retrieve`メソッドでナレッジ検索ロジックを実装する必要があります。完全なコードは[langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo)で見つけることができます。 + +```python +# Auto generated by LangBot Plugin SDK. +# Please refer to https://docs.langbot.app/en/plugin/dev/tutor.html for more details. +... + +class FastGPT(KnowledgeRetriever): + + async def retrieve(self, context: RetrievalContext) -> list[RetrievalResultEntry]: + """FastGPTナレッジベースからナレッジを検索""" + + # 1. 設定パラメータを取得 + api_base_url = self.config.get('api_base_url', 'http://localhost:3000') + api_key = self.config.get('api_key') + dataset_id = self.config.get('dataset_id') + search_mode = self.config.get('search_mode', 'embedding') + using_rerank = self.config.get('using_rerank', False) + + # 2. パラメータ検証 + if not api_key or not dataset_id: + logger.error("Missing required configuration: api_key or dataset_id") + return [] + + # 3. APIリクエストを構築 + url = f"{api_base_url.rstrip('/')}/api/core/dataset/searchTest" + headers = { + "Authorization": f"Bearer {api_key}", + "Content-Type": "application/json" + } + payload = { + "datasetId": dataset_id, + "text": context.query, # RetrievalContextからクエリテキストを取得 + "searchMode": search_mode, + "usingReRank": using_rerank, + } + + try: + # 4. 外部APIを呼び出す + async with httpx.AsyncClient() as client: + response = await client.post(url, json=payload, headers=headers, timeout=30.0) + response.raise_for_status() + result = response.json() + + # 5. レスポンスを解析してRetrievalResultEntryに変換 + results = [] + for record in result.get('data', []): + # メインデータと補助データをコンテンツとして結合 + content_text = '\n'.join([ + record.get('q', ''), + record.get('a', '') + ]).strip() + + # 検索結果エントリを作成 + entry = RetrievalResultEntry( + id=record.get('id', ''), + content=[ContentElement.from_text(content_text)], + metadata={ + 'dataset_id': record.get('datasetId', ''), + 'source_name': record.get('sourceName', ''), + 'score': record.get('score', 0.0), + }, + # 類似度スコアを距離に変換(スコアが高いほど距離が小さい) + distance=1.0 - float(record.get('score', 0.0)), + ) + results.append(entry) + + logger.info(f"Retrieved {len(results)} chunks from FastGPT dataset {dataset_id}") + return results + + except httpx.HTTPStatusError as e: + logger.error(f"HTTP error from FastGPT API: {e.response.status_code} - {e.response.text}") + return [] + except httpx.RequestError as e: + logger.error(f"Request error when calling FastGPT API: {str(e)}") + return [] + except Exception as e: + traceback.print_exc() + logger.error(f"Unexpected error during retrieval: {str(e)}") + return [] +``` + +### 検索コンテキスト + +`RetrievalContext`にはこの検索のコンテキスト情報が含まれます: + +```python +class RetrievalContext(pydantic.BaseModel): + """ナレッジ検索コンテキスト""" + + query: str + """クエリテキスト、ユーザーの検索質問""" +``` + +### 検索結果 + +検索結果は`RetrievalResultEntry`オブジェクトのリストに変換する必要があり、各オブジェクトは検索されたナレッジチャンクを表します: + +```python +class RetrievalResultEntry(pydantic.BaseModel): + """単一検索結果エントリ""" + + id: str + """結果ID、このエントリを一意に識別""" + + content: list[ContentElement] + """結果コンテンツ、ContentElement.from_text()を使用してテキストコンテンツを作成""" + + metadata: dict[str, Any] + """結果メタデータ、ソース、スコアなど、任意のキーと値のペアを含めることができます""" + + distance: float + """距離スコア、クエリとの関連性を示します(小さいほど関連性が高い) + 通常は1.0 - similarity_scoreとして計算されます""" +``` + +### 設定パラメータの取得 + +`self.config.get(パラメータ名, デフォルト値)`を使用して、ユーザーが設定したパラメータ値を取得します: + +```python +# 文字列パラメータを取得 +api_base_url = self.config.get('api_base_url', 'http://localhost:3000') + +# 数値パラメータを取得 +limit = self.config.get('limit', 5000) +similarity = self.config.get('similarity', 0.0) + +# ブールパラメータを取得 +using_rerank = self.config.get('using_rerank', False) + +# selectパラメータを取得 +search_mode = self.config.get('search_mode', 'embedding') +``` + +## リトリーバーのテスト + +作成後、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。その後、LangBotで: + +1. 「ナレッジベース」ページに移動 +2. 外部ナレッジベースを追加 +3. プラグインが提供するナレッジリトリーバーを選択し、設定を入力 + + + +保存後、LangBotパイプラインでこのナレッジベースを選択できます。 diff --git a/docs/ja/plugin/dev/components/tool.md b/docs/ja/plugin/dev/components/tool.md new file mode 100644 index 000000000..375927823 --- /dev/null +++ b/docs/ja/plugin/dev/components/tool.md @@ -0,0 +1,174 @@ +# コンポーネント: Tool + +LangBotの組み込みLocal Agentは、実行中にツールを呼び出して外部世界と対話します。現在、プラグインとMCPの両方を通じてツールを追加することがサポートされています。 + +## Toolコンポーネントの追加 + +1つのプラグインには任意の数のツールを含めることができます。プラグインディレクトリでコマンド`lbp comp Tool`を実行し、プロンプトに従ってツール設定を入力します。 + +```bash +➜ HelloPlugin > lbp comp Tool +Generating component Tool... +Tool name: get_weather_alerts +Tool description: Get weather alerts for a US state. +Component Tool generated successfully. +組件 Tool 生成成功。 +``` + +これにより、`components/tools/`ディレクトリに`get_weather_alerts.yaml`と`get_weather_alerts.py`ファイルが生成されます。`.yaml`ファイルはツールの基本情報を定義し、`.py`ファイルはツールハンドラです: + +```bash +➜ HelloPlugin > tree +... +├── components +│ ├── __init__.py +│ └── tools +│ ├── __init__.py +│ ├── get_weather_alerts.py +│ └── get_weather_alerts.yaml +... +``` + +## マニフェストファイル: Tool + +```yaml +apiVersion: v1 # 変更しないでください +kind: Tool # 変更しないでください +metadata: + name: get_weather_alerts # ツール名、LLM認識用 + label: + en_US: GetWeatherAlerts # ツール表示名、LangBot UIに表示、多言語対応 + zh_Hans: GetWeatherAlerts + description: + en_US: 'Get weather alerts for a US state.' # ツール説明、LangBot UIに表示、多言語対応。オプション + zh_Hans: '獲取美国某个州的天気預警' +spec: + parameters: [] # ツールパラメータ、会話コンテキストに基づいてLLMが生成する値 + llm_prompt: 'Get weather alerts for a US state.' # ツールプロンプト、LLMがこのツールを呼び出すかどうかを判断するため +execution: + python: + path: get_weather_alerts.py # ツールハンドラ、変更しないでください + attr: GetWeatherAlerts # ツールハンドラクラス名、get_weather_alerts.pyのクラス名と一致 +``` + +## プラグイン処理 + +以下のコードがデフォルトで生成されます(components/tools/.py)。`GetWeatherAlerts`クラスの`call`メソッドでこのツールの呼び出しと戻り値のロジックを実装する必要があります。 + +```python +# Auto generated by LangBot Plugin SDK. +# Please refer to https://docs.langbot.app/en/plugin/dev/tutor.html for more details. +from __future__ import annotations + +from typing import Any + +from langbot_plugin.api.definition.components.tool.tool import Tool +from langbot_plugin.api.entities.builtin.provider import session as provider_session + + +class GetWeatherAlerts(Tool): + + async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str: + """Fill your tool code here""" + return {} +``` + +`call`メソッドでこのツールを実装します: + +:::info +天気検索ツールの例は、MCPの[サーバー作成例](https://modelcontextprotocol.io/quickstart/server)から来ています。 +::: + +```python +from __future__ import annotations + +from typing import Any + +from langbot_plugin.api.definition.components.tool.tool import Tool +from langbot_plugin.api.entities.builtin.provider import session as provider_session +import httpx + +# 定数 +NWS_API_BASE = "https://api.weather.gov" +USER_AGENT = "weather-app/1.0" + + +async def make_nws_request(url: str) -> dict[str, Any] | None: + """適切なエラー処理を使用してNWS APIにリクエストを行う。""" + headers = { + "User-Agent": USER_AGENT, + "Accept": "application/geo+json" + } + async with httpx.AsyncClient() as client: + try: + response = await client.get(url, headers=headers, timeout=30.0) + response.raise_for_status() + return response.json() + except Exception: + return None + +def format_alert(feature: dict) -> str: + """アラート機能を読みやすい文字列にフォーマットする。""" + props = feature["properties"] + return f""" +Event: {props.get('event', 'Unknown')} +Area: {props.get('areaDesc', 'Unknown')} +Severity: {props.get('severity', 'Unknown')} +Description: {props.get('description', 'No description available')} +Instructions: {props.get('instruction', 'No specific instructions provided')} +""" + +class GetWeatherAlerts(Tool): + + async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str: + """Fill your tool code here""" + state = params.get("state", "CA") + + url = f"{NWS_API_BASE}/alerts/active/area/{state}" + data = await make_nws_request(url) + + if not data or "features" not in data: + return "Unable to fetch alerts or no alerts found." + + if not data["features"]: + return "No active alerts for this state." + + alerts = [format_alert(feature) for feature in data["features"]] + return "\n---\n".join(alerts) +``` + +このツールでは、`params`から`state`パラメータを取得し、NWS APIを呼び出してその州の天気アラートを取得する必要があるため、マニフェストファイルの`parameters`で`state`パラメータを定義する必要があります。 + +`parameters`フォーマットは[JSON Schema](https://json-schema.org/docs)に従い、[OpenAI Function Calling機能](https://platform.openai.com/docs/guides/function-calling#defining-functions)でサポートされており、そのルートタイプは`type: object`に固定されています。`properties`にパラメータを追加し、`required`に必須パラメータの説明を追加してください。 + +```yaml +... +spec: + parameters: + type: object # 変更しないでください + properties: # 変更しないでください、ここにパラメータを追加 + state: + type: string + description: 'Two-letter US state code (e.g. CA, NY)' + required: # ここに必須パラメータの説明を追加 + - state +... +``` + +このツールは`httpx`ライブラリも使用しているため、プラグインディレクトリの`requirements.txt`に`httpx`依存関係を追加する必要があります。 + +```txt +# HelloPlugin/requirements.txt +langbot-plugin # デフォルトで既に存在 +httpx +``` + +次に、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。LangBotでツール呼び出しをサポートするモデルを設定し、対応するパイプラインでそのモデルの使用を選択してこのツールを使用します。 + + + +## 次のステップ + +ツールの基本的な使い方を学びました。次は: + +- [プラグイン共通API](/en/plugin/dev/apis/common)を確認してください diff --git a/docs/ja/plugin/dev/directory-structure.md b/docs/ja/plugin/dev/directory-structure.md new file mode 100644 index 000000000..b3aaf4389 --- /dev/null +++ b/docs/ja/plugin/dev/directory-structure.md @@ -0,0 +1,191 @@ +# プラグインディレクトリ構造 + +:::info 目次 +[[toc]] +::: + +このドキュメントでは、LangBotプラグインの標準ディレクトリ構造とファイル組織仕様を紹介し、開発者が準拠したプラグインを作成できるように支援します。 + +## 基本ディレクトリ構造 + +標準的なLangBotプラグインは次のディレクトリ構造に従う必要があります: + +``` +MyPlugin/ +├── manifest.yaml # プラグインマニフェストファイル(必須) +├── main.py # プラグインメインエントリファイル(必須) +├── README.md # 英語プラグインドキュメント(必須) +├── readme/ # 多言語READMEディレクトリ(オプション) +│ ├── README_zh_Hans.md # 簡体字中国語ドキュメント +│ ├── README_ja_JP.md # 日本語ドキュメント +│ └── README_zh_Hant.md # 繁体字中国語ドキュメント(オプション) +├── assets/ # リソースファイルディレクトリ +│ ├── icon.svg # プラグインアイコン(推奨) +│ └── ... # その他のリソースファイル +├── components/ # コンポーネントディレクトリ +│ ├── event_listener/ # イベントリスナーコンポーネント +│ ├── commands/ # コマンドコンポーネント +│ └── tools/ # ツールコンポーネント +├── requirements.txt # Python依存関係(オプション) +└── config/ # 設定ディレクトリ(オプション) +``` + +## 多言語README仕様 + +### ファイル配置仕様 + +LangBotプラグインは、異なる言語のユーザーにローカライズされたプラグイン説明を提供するために、多言語READMEドキュメントをサポートしています。 + +**重要な仕様:** + +1. **ルート`README.md`(必須)** + - **英語**で記述する必要があります + - プラグインのデフォルトドキュメントとして機能します + - 要求された言語バージョンが存在しない場合のフォールバックとして使用されます + +2. **`readme/`ディレクトリ(オプション)** + - **非英語**のREADMEドキュメントを保存するために使用 + - ファイル命名形式: `README_{言語コード}.md` + +### サポートされる言語コード + +[RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646)標準に従い、LangBotは現在次の言語コードをサポートしています: + +| 言語 | 言語コード | ファイル名 | 配置場所 | +|----------|---------------|----------|----------| +| 英語 | `en`または`en_US` | `README.md` | **プラグインルートディレクトリ** | +| 簡体字中国語 | `zh_Hans` | `README_zh_Hans.md` | `readme/`ディレクトリ | +| 繁体字中国語 | `zh_Hant` | `README_zh_Hant.md` | `readme/`ディレクトリ | +| 日本語 | `ja_JP` | `README_ja_JP.md` | `readme/`ディレクトリ | + +### ディレクトリ構造の例 + +``` +MyPlugin/ +├── README.md # ✅ 英語版(必須、ルートディレクトリ) +└── readme/ # ✅ 多言語ディレクトリ + ├── README_zh_Hans.md # ✅ 簡体字中国語 + ├── README_ja_JP.md # ✅ 日本語 + └── README_zh_Hant.md # ✅ 繁体字中国語 +``` + +### 誤った例 + +❌ **誤り: readme/ディレクトリに英語READMEを配置** + +``` +MyPlugin/ +├── readme/ +│ ├── README_en.md # ❌ 誤り: 英語はreadme/に配置すべきではない +│ └── README_zh_Hans.md +``` + +❌ **誤り: ルートREADME.mdに非英語コンテンツが含まれる** + +```markdown +# MyPlugin + +This is a plugin... + +これはプラグインです... # ❌ 誤り: ルートREADME.mdは英語のみを含むべき +``` + +### README言語フォールバックロジック + +ユーザーが特定の言語でREADMEを要求した場合、LangBotは次の順序で検索します: + +1. `readme/README_{言語コード}.md`を読み取ろうとします +2. 見つからない場合は、ルート`README.md`(英語版)にフォールバックします + +**例:** + +- ユーザーが簡体字中国語(`zh_Hans`)を要求 + - → `readme/README_zh_Hans.md`を検索 + - → 見つからない場合は、`README.md`(英語版)を返します + +- ユーザーが日本語(`ja_JP`)を要求 + - → `readme/README_ja_JP.md`を検索 + - → 見つからない場合は、`README.md`(英語版)を返します + +## リソースファイルディレクトリ + +### assets/ディレクトリ + +`assets/`ディレクトリはプラグインの静的リソースファイルを保存するために使用されます。 + +**推奨構造:** + +``` +assets/ +├── icon.svg # プラグインアイコン(SVG形式推奨) +├── example.png # 例画像 +├── screenshot1.png # スクリーンショット +└── logo.png # ロゴ画像 +``` + +**アイコン仕様:** + +- プラグインアイコンとして`icon.svg`を使用することを推奨 +- サポートされる形式: `.svg`、`.png`、`.jpg`、`.jpeg`、`.gif` +- 推奨サイズ: 最低256x256ピクセル +- `manifest.yaml`での参照: `icon: assets/icon.svg` + +### READMEでのリソース参照 + +READMEドキュメントで相対パスを使用してassets/ディレクトリの画像を参照できます: + +```markdown +# MyPlugin + +![例](./assets/example.png) + +![スクリーンショット](./assets/screenshot1.png) +``` + +**注意:** プラグインをLangBot Spaceにアップロードすると、リソースファイルが自動的に処理およびホストされ、ユーザーがREADMEを表示したときに画像が正しく表示されます。 + +## コンポーネントディレクトリ + +プラグイン機能はコンポーネントを通じて実装され、タイプ別に`components/`ディレクトリに整理する必要があります: + +``` +components/ +├── event_listener/ # イベントリスナー +│ ├── on_message.py +│ └── on_message.yaml +├── commands/ # コマンド +│ ├── hello.py +│ └── hello.yaml +└── tools/ # ツール + ├── search.py + └── search.yaml +``` + +コンポーネント開発の詳細な仕様については、[コンポーネントの追加](/en/plugin/dev/components/add)を参照してください。 + +## 設定ファイル + +### manifest.yaml + +プラグインマニフェストファイル`manifest.yaml`はコア設定ファイルであり、プラグインメタデータ、設定項目、コンポーネントリストなどの情報が含まれます。 + +詳細な手順については、[プラグイン設定情報の完成](/en/plugin/dev/basic-info)を参照してください。 + +### requirements.txt + +プラグインが追加のPython依存関係を必要とする場合は、ルートディレクトリに`requirements.txt`ファイルを作成します: + +``` +requests>=2.28.0 +beautifulsoup4>=4.11.0 +pillow>=9.0.0 +``` + +**注意:** LangBotは、プラグインのインストール時に`requirements.txt`にリストされている依存関係を自動的にインストールします。 + +## 関連ドキュメント + +- [基本チュートリアル](/en/plugin/dev/tutor) - 最初のプラグインを作成する方法を学ぶ +- [プラグイン設定情報の完成](/en/plugin/dev/basic-info) - manifest.yamlの設定 +- [コンポーネントの追加](/en/plugin/dev/components/add) - プラグインコンポーネントの開発 +- [マーケットプレイスに公開](/en/plugin/dev/publish/market) - プラグインを配布 diff --git a/docs/ja/plugin/dev/migration.md b/docs/ja/plugin/dev/migration.md new file mode 100644 index 000000000..27f511a9b --- /dev/null +++ b/docs/ja/plugin/dev/migration.md @@ -0,0 +1,27 @@ +# 移行ガイド + +このチュートリアルでは特定の考慮事項を強調しています。まず現在のバージョンのプラグインチュートリアルをお読みいただき、その後このドキュメントをプラグイン移行のリファレンスとしてご使用ください。 + +## 3.xサポートの非同期プラグインからの移行 + +:::info +プラグインの特徴: +- 主な期間: 2024.2 ~ 2025.8 +- 登録方法: `main.py`のプラグインクラスで`@handler`デコレータを使用してイベントリスナーを登録し、`@llm_func`デコレータを使用してコンテンツ関数(ツール)を登録; すべてのハンドラ関数は非同期関数(async def) +::: + +- プラグインとコンポーネント登録方法: 以前の単一プラグインクラスデコレータ登録方法から、マニフェストファイル登録方法に変更されました。[マニフェストファイル](/en/plugin/dev/basic-info)を参照してください; そして、異なるタイプのコンポーネントを独立して分離しました。詳細については、[コンポーネントの追加](/en/plugin/dev/components/add)を参照してください。 +- メッセージチェーンエンティティ: リファクタリングされました。各メッセージチェーン要素の構築方法では、**名前付きパラメータ**の明示的な渡しが必要になりました。[メッセージプラットフォームエンティティ](/en/plugin/dev/apis/messages)を参照してください。 +- イベントリスナー: 後方互換性を提供しますが、コンテキストで`query: Query`オブジェクトは提供されなくなりました。詳細については、[パイプラインイベント](/en/plugin/dev/apis/pipeline-events)を参照してください。 +- コマンドコンポーネント: リファクタリングされました。[Commandコンポーネント](/en/plugin/dev/components/command)を参照してください。 + +## 2.xおよび3.xサポートの同期プラグインからの移行 + +:::info +プラグインの特徴: +- 主な期間: 2023.1 ~ 2024.2 +- 登録方法: `main.py`のプラグインクラスで`@on`デコレータを使用してイベントリスナーを登録し、`@func`デコレータを使用してコンテンツ関数(ツール)を登録; すべてのハンドラ関数は同期関数(def) +::: + +- 同期から非同期へ: プラグインランタイムは完全に非同期(asyncioベース)に変更されました。IO操作を含むすべてのプラグインコードを非同期記述に変更してください。 +- 詳細な内容については、上記の3.x非同期プラグイン移行ガイドを参照してください。 diff --git a/docs/ja/plugin/dev/publish/github.md b/docs/ja/plugin/dev/publish/github.md new file mode 100644 index 000000000..71ad13356 --- /dev/null +++ b/docs/ja/plugin/dev/publish/github.md @@ -0,0 +1,23 @@ +# GitHub経由でプラグインを配布 + +プラグインをGitHubにアップロードし、リポジトリのReleaseを作成して`.lbpkg`ファイルをアップロードすることで、他のユーザーがLangBotでインストールできるようになります。 + +## プラグインのビルド + +プラグインディレクトリで次のコマンドを実行します: + +```bash +lbp build +``` + +これにより、`dist`ディレクトリに`.lbpkg`ファイルが生成されます。 + +## Releaseの作成 + +プラグインをGitHubにアップロードし、プラグインリポジトリのReleaseページに移動し、Releaseを作成をクリックして、先ほどビルドした`.lbpkg`ファイルをアップロードします。 + + + +## プラグインのインストール + +LangBotのプラグイン管理ページで、右上隅をクリックしてGitHubインストール方法を選択します。 diff --git a/docs/ja/plugin/dev/publish/market.md b/docs/ja/plugin/dev/publish/market.md new file mode 100644 index 000000000..49f2420f0 --- /dev/null +++ b/docs/ja/plugin/dev/publish/market.md @@ -0,0 +1,65 @@ +# プラグインマーケットプレイスに公開 + +CLI経由で[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)にプラグインを公開します。 + +## LangBot Spaceでアカウントを作成 + +LangBot SpaceはLangBotの集中サービスプラットフォームです。[LangBot Space](https://space.langbot.app)にアクセスし、右上隅をクリックしてGitHubでログインし、アカウントを作成してください。 + + + +GitHubの認証ページにリダイレクトされますので、プロンプトに従って認証を完了してください。 + +## CLIを使用してLangBot Spaceにログイン + +任意のディレクトリでコマンド`lbp login`を実行します: + +```bash +➜ HelloPlugin > lbp login +Starting LangBot CLI login process... +Generating device code... + +================================================== +Please copy the user code and complete verification in your browser: +User Code: 6CD64D56 +Verification URL: https://space.langbot.app/auth/device +Device code expires in: 120 seconds +================================================== + +Waiting for verification... +``` + +`Verification URL`をクリックしてLangBot Spaceにリダイレクトし、`User Code`を入力してログインを完了してください。 + + + +```bash +================================================== +✅ Login successful! +Access token saved to: ~/.langbot/cli/config.json +Token type: Bearer +Expires in: 21600 seconds +================================================== +``` + +ログインが成功したら、CLIを使用してプラグインをアップロードできます。 + +## プラグインのアップロード + +プラグインディレクトリで`lbp publish`を実行してください: + +```bash +➜ HelloPlugin > lbp publish +Building plugin to dist/tmp... + - Skipping ignored directory: dist + - Skipping ignored directory: __pycache__ + ... +Plugin built successfully: dist/tmp/RockChinQ-HelloPlugin-0.1.0.lbpkg +✅ Plugin published successfully. You can check it on https://https://space.langbot.app/market +``` + +[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)でプラグイン提出タスクを確認できます。承認をお待ちください。承認後、マーケットプレイスでプラグインを表示できます。 + + + +ご質問がある場合は、`hello@langbot.app`にメールを送信するか、[コミュニティ](/en/insight/community)を通じてお問い合わせください。 diff --git a/docs/ja/plugin/dev/tutor.md b/docs/ja/plugin/dev/tutor.md new file mode 100644 index 000000000..f13db80e3 --- /dev/null +++ b/docs/ja/plugin/dev/tutor.md @@ -0,0 +1,133 @@ +# プラグイン開発チュートリアル + +## アーキテクチャの基礎 + +バージョン4.0では、高セキュリティで柔軟性の高い本番環境グレードのプラグインシステムを導入し、開発者に豊富なAPIと使いやすいサポートツールを提供しています。 + + + +Plugin Runtimeは、プラグインのライフサイクルを管理し、LangBotとプラグイン間の相互作用を調整するために使用されます。`stdio`と`websocket`の2つの動作モードがあります。LangBotがユーザーによって直接起動される場合(コンテナ内で実行されていない場合)、`stdio`モードを使用します。これは個人ユーザーや軽量環境で一般的です。LangBotがコンテナ内で実行される場合、`websocket`モードを使用します。これは本番環境専用に設計されています。 + +Plugin Runtimeは、インストールされた各プラグインを自動的に起動し、stdioを通じて相互作用します。プラグイン開発シナリオでは、開発者は`lbp`コマンドラインツールを使用してプラグインを起動し、WebSocketを介して実行中のRuntimeに接続してデバッグできます。 + +### プラグイン構造 + +プラグインのディレクトリ構造は次のようになります: + +```bash +➜ HelloPlugin > tree +. +├── assets +│ └── icon.svg # プラグインアイコン、プラグインマーケットプレイスページに表示 +├── components # プラグインコンポーネントディレクトリ、さまざまなコンポーネントコードとマニフェストファイルを保存 +│ ├── __init__.py +│ ├── commands +│ │ ├── __init__.py +│ │ ├── info.py +│ │ └── info.yaml +│ ├── event_listener +│ │ ├── __init__.py +│ │ ├── default.py +│ │ └── default.yaml +│ └── tools +│ ├── __init__.py +│ ├── get_weather_alerts.py +│ └── get_weather_alerts.yaml +├── main.py # プラグインメインプログラム、プラグインライフサイクルをリッスン +├── manifest.yaml # プラグインマニフェストファイル、プラグインメタデータを記述 +├── README.md # プラグインドキュメントファイル、プラグイン機能と使用方法を記述、プラグインマーケットプレイスページに表示 +└── requirements.txt # プラグイン依存関係ファイル +``` + +main.pyのプラグインクラスは各プラグインの共通コードで、プラグイン起動時に初期化され、コンテキスト情報(設定など)が渡されます。ここでプラグインの初期化とシャットダウンロジックを実装できます。プラグインクラスは`langbot_plugin.api.definition.plugin.BasePlugin`を継承し、[LangBotグローバルAPI](/en/plugin/dev/apis/common)を提供します。 + +各コンポーネントはプラグインのコア機能モジュールであり、必要に応じて[追加および削除](/en/plugin/dev/components/add)できます。異なるコンポーネントは異なる状況で呼び出され、後でプラグイン機能を簡単に拡張できます。各コンポーネントは`langbot_plugin.api.definition.components`パッケージ下のさまざまなコンポーネント基底クラスから直接継承し、`plugin: BasePlugin`オブジェクトを含み、プラグインのAPIを直接呼び出すことができます。 + +::: info +- 詳細なAPIドキュメントについては、[APIリファレンス](/en/plugin/dev/apis/common)を参照してください。 + +このチュートリアルを続けて読んで、プラグイン開発プロセスを理解してください。 +::: + +## CLIのインストール + +Python 3.10以上がインストールされており、[uvパッケージマネージャー](https://docs.astral.sh/uv/)がインストールされていることを確認してください。 + +任意の空のディレクトリで次のコマンドを実行して、LangBot CLIとSDKをインストールします: + +```bash +pip install -U langbot_plugin +``` + +## プラグインディレクトリの初期化 + +プラグイン名が`HelloPlugin`であると仮定して、任意のディレクトリに`HelloPlugin`ディレクトリを作成し、そのディレクトリに入り、コマンドを実行してプラグインを初期化します: + +```bash +lbp init +``` + +プロンプトに従って`Author`、`Description`などの情報を入力します。 + +:::info +`lbp init HelloPlugin`コマンドを使用して、サブディレクトリ`HelloPlugin`でプラグインを初期化することもできます。 + + +::: + +この操作により、プラグインの初期ファイルが生成されます。お気に入りのエディターで`HelloPlugin`ディレクトリを開き、プラグインコードの記述を開始できます。 + +:::info +`lbp`コマンドで「command not found」エラーが発生した場合、`PATH`環境変数が適切に設定されていない可能性があります。 +`lbp`コマンドの代わりに`python -m langbot_plugin.cli.__init__`を使用できます。 + +例えば: + +```bash +python -m langbot_plugin.cli.__init__ init HelloPlugin +cd HelloPlugin +``` +::: + +## デバッグモードの開始 + +まずLangBotをデプロイして起動し、Plugin Runtimeが実行されてポート`5401`をリッスンしていることを確認する必要があります。 + +::: info +Runtimeには2つの起動モードがあります: + +- `Stdio`モード: 起動パラメータ`--standalone-runtime`なしでソースコードを使用してLangBotを起動すると、LangBotは自動的にPlugin Runtimeをサブプロセスとして起動し、`stdio`(標準入出力ストリーム)を通じてPlugin Runtimeと通信します。この場合、RuntimeはLangBotルートディレクトリの`data/plugins`ディレクトリからプラグインをロードし、LangBotホストのポート`5401`をデバッグポートとしてリッスンします。 + +- `WebSocket`モード: + - 本番環境: 公式の`docker-compose.yaml`を使用してLangBotを起動すると、Plugin Runtimeは別のコンテナで実行され、起動パラメータ`--standalone-runtime`のためにLangBotはWebSocketモードでPlugin Runtimeと通信します。Runtimeコンテナの5401ポートはデフォルトでホストの5401ポートにマッピングされます。 + - 開発環境: 起動パラメータ`--standalone-runtime`を使用してソースコードでLangBotを起動すると、LangBotは`data/config.yaml`で設定された`plugin.runtime_ws_url`アドレス(ポートは通常5400)に従って既に起動されているPlugin Runtimeに接続します。スタンドアロンのPlugin Runtimeを自分で起動する必要があります。[Plugin Runtimeの開発](/en/develop/plugin-runtime)を参照してください。 + +`stdio`または`websocket`モードのいずれの場合でも、Plugin Runtimeはそのホストのポート`5401`をプラグインデバッグ接続のデバッグポートとしてリッスンします。 + +プラグインを開発する際は、[開発設定](/en/develop/dev-config)方法に従ってLangBotを起動することをお勧めします。これによりPlugin RuntimeがStdioモードで起動され、プラグイン開発が容易になります。 +::: + +プラグインディレクトリの`.env.example`ファイルを`.env`にコピーし、`DEBUG_RUNTIME_WS_URL`をPlugin RuntimeのWebSocketアドレスに確認または変更します。 + +```bash +cp .env.example .env +``` + +プラグインデバッグを開始すると、プラグインの出力が表示されます: + +```bash +lbp run +``` + + + +そして、LangBotのWebUIでこのプラグインがロードされたことを確認できます。 + + + +## 次のステップ + +このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。 + +- プラグイン情報の変更: プラグインは基本的なプラグイン情報で作成されました。[プラグイン情報を完成させて](/en/plugin/dev/basic-info)ください。 +- コンポーネントの追加: プラグインコンポーネントはプラグインのコア機能ユニットです。必要に応じて[コンポーネントを追加](/en/plugin/dev/components/add)できます。 diff --git a/docs/ja/plugin/plugin-intro.md b/docs/ja/plugin/plugin-intro.md new file mode 100644 index 000000000..6829b645a --- /dev/null +++ b/docs/ja/plugin/plugin-intro.md @@ -0,0 +1,53 @@ +# LangBotプラグイン + +LangBotは、大規模言語モデルツール、コマンド、メッセージングプラットフォームアダプター、LLMリクエスターなど、さまざまな内部コンポーネントで構成されています。拡張性と柔軟性の要件を満たすために、本番環境グレードのプラグインシステムを実装しました。 + +各プラグインは独立したプロセスで実行され、Plugin Runtimeによって統一的に管理されます。 + + + +## プラグイン構造 + +プラグインは、特定の機能に基づいて次のコンポーネントを提供できます: + +- イベントハンドラー: パイプライン実行中のイベントをリッスンし、コンテキストやパイプラインを変更します。 +- コマンド: `!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。 +- ツール: LangBotの組み込みLocal Agentの実行中にLLMによって呼び出されます。 +- ナレッジリトリーバー: 外部ナレッジベースから関連するナレッジを検索するために使用されます。 + +将来的には、プラグイン実装のためにより多くのコンポーネントタイプがサポートされます。 + +## プラグインのインストール + +現在、プラグインパッケージのアップロードとプラグインマーケットプレイスからのプラグインのインストールをサポートしています。 +LangBotのプラグイン管理ページで、右上隅をクリックしてインストール方法を選択します。 + + + +`Upload Local`をクリックして、他の人が共有した`.lbpkg`ファイルまたはマーケットプレイスからダウンロードしたファイルを選択してプラグインをインストールします。 + +または、プラグインマーケットプレイスタブをクリックし、プラグインを選択してインストールをクリックします。 + + + +プラグインをインストールした後、パイプライン設定ページでプラグインを選択する必要があります。 + + + +## プラグイン管理 + +### プラグイン設定 + +一部のプラグインでは、特定の設定項目を入力する必要がある場合があります(プラグインREADMEの指示を参照)。プラグインカードをクリックしてプラグイン詳細ページに入り、プロンプトに従って必要な情報を取得して入力します。 + + + +### プラグインの更新 + +プラグインマーケットプレイスからインストールされたプラグインのみを更新できます。 + + + +## プラグインマーケットプレイス + +プラグインマーケットプレイスには、LangBotの内部`プラグイン管理`ページからアクセスするか、スタンドアロンサイト[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)にアクセスできます。 diff --git a/docs/ja/tags/[operationId].md b/docs/ja/tags/[operationId].md new file mode 100644 index 000000000..587c310a1 --- /dev/null +++ b/docs/ja/tags/[operationId].md @@ -0,0 +1,13 @@ +--- +aside: false +outline: [2, 3] +title: Service API +--- + + + + diff --git a/docs/ja/tags/[operationId].paths.mts b/docs/ja/tags/[operationId].paths.mts new file mode 100644 index 000000000..1fa0b9cfd --- /dev/null +++ b/docs/ja/tags/[operationId].paths.mts @@ -0,0 +1,18 @@ +import { usePaths } from 'vitepress-openapi' +import spec from '../../assets/service-api-openapi-en.json' with { type: 'json' } + +export default { + paths() { + return usePaths({ spec }) + .getPathsByVerbs() + .filter(item => item && item.operationId) + .map(({ operationId, summary }) => { + return { + params: { + operationId, + pageTitle: `${summary || operationId} - LangBot API`, + }, + } + }) + }, +} diff --git a/docs/ja/tags/[tag].md b/docs/ja/tags/[tag].md new file mode 100644 index 000000000..c2902a5aa --- /dev/null +++ b/docs/ja/tags/[tag].md @@ -0,0 +1,16 @@ +--- +aside: false +outline: false +title: Service API +--- + + + + diff --git a/docs/ja/tags/[tag].paths.mts b/docs/ja/tags/[tag].paths.mts new file mode 100644 index 000000000..7932baa1b --- /dev/null +++ b/docs/ja/tags/[tag].paths.mts @@ -0,0 +1,17 @@ +import { usePaths } from 'vitepress-openapi' +import spec from '../../assets/service-api-openapi-en.json' with { type: 'json' } + +export default { + paths() { + return usePaths({ spec }) + .getTags() + .map(({ name }) => { + return { + params: { + tag: name, + pageTitle: `${name} - LangBot API`, + }, + } + }) + }, +} diff --git a/docs/ja/tags/readme.md b/docs/ja/tags/readme.md new file mode 100644 index 000000000..2a9e2d860 --- /dev/null +++ b/docs/ja/tags/readme.md @@ -0,0 +1,21 @@ +# Service API 概要 + +LangBotは、外部サービスと統合するための一連のAPIを提供します。これらのAPIはAPIキーで認証され、HTTP APIのサブセットです。フロントエンドとバックエンドの通信用APIドキュメントを表示するには、[開発](/en/develop/dev-config)セクションにアクセスしてください。 + +::: warning +Service APIは現在ベータ版であり、一部のAPIは頻繁に変更される可能性があります。 +::: + +## APIキーの取得 + +WebUIのサイドバーにある`API Keys`ボタンをクリックして、APIキーを作成します。 + +![create_api_key](/assets/image/zh/api/create_api_key.png) + +作成後、APIキーをコピーして保存します。 + +![copy_api_key](/assets/image/zh/api/copy_api_key.png) + +## APIの使用 + +左サイドバーには、利用可能なすべてのAPIが一覧表示されています。インスタンスアドレス(バックエンドが公開するポートアドレス、デフォルトは`http://localhost:5300`)とAPIキーを入力し、`Try it out`ボタンをクリックしてAPIを呼び出すことができます。 diff --git a/docs/ja/tags/webhook.md b/docs/ja/tags/webhook.md new file mode 100644 index 000000000..c13a2ab9d --- /dev/null +++ b/docs/ja/tags/webhook.md @@ -0,0 +1,104 @@ +# Webhook + +Webhookを使用すると、ボットメッセージイベントを外部サービスに送信して処理できます。 + +## Webhookの設定 + +1. LangBot WebUIで、サイドバーの「API統合」をクリックします +2. 「Webhooks」タブに切り替えます +3. 「+」をクリックして新しいWebhookを作成します +4. 以下を入力します: + - **Name**: Webhook識別子 + - **URL**: イベントを受信するターゲットURL + - **Description**: オプション + - **Status**: 有効または無効 + +## イベント形式 + +### 個人メッセージ (bot.person_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.person_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "Message content" + } + ], + "timestamp": 1234567890 + } +} +``` + +### グループメッセージ (bot.group_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.group_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "group": { + "id": "group-id", + "name": "Group Name" + }, + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "Message content" + } + ], + "timestamp": 1234567890 + } +} +``` + +## レスポンス形式 + +WebhookサービスはJSONを返す必要があります: + +```json +{ + "status": "ok", + "skip_pipeline": false +} +``` + +### パラメーター + +- **status**: 処理ステータス(「ok」を推奨) +- **skip_pipeline**: LangBotパイプライン処理をスキップするかどうか + - `true`: メッセージはパイプラインで続行されません + - `false`: メッセージは通常どおり続行されます + +::: tip +`skip_pipeline`を使用すると、メッセージ処理を完全に引き継ぐことができます。`true`の場合、メッセージはWebhookサービスによってのみ処理され、LangBotのAI機能はトリガーされません。 +::: + +## 統合例 + +### Dify Workflow + +[dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger)プラグインを使用して、LangBotのWebhookイベントを受信し、Difyでワークフローを作成できます。 + +## 注意事項 + +- Webhook URLはアクセス可能である必要があります +- リクエストタイムアウト: 15秒 +- 失敗したリクエストは通常の処理に影響しません +- 複数のWebhookは並行して実行されます +- `skip_pipeline: true`を返すWebhookがある場合、パイプライン処理はスキップされます diff --git a/docs/ja/workshop/302ai-integration.md b/docs/ja/workshop/302ai-integration.md new file mode 100644 index 000000000..b0ad84e40 --- /dev/null +++ b/docs/ja/workshop/302ai-integration.md @@ -0,0 +1,5 @@ +# 302 AIとのモデル統合 + +WebUIページを開き、モデルを追加する際に[302 AI](https://share.302.ai/SuTG99)を選択します。 + +![model](/assets/image/zh/workshop/302ai-integration/model.png) diff --git a/docs/ja/workshop/impl-platform-adapter.md b/docs/ja/workshop/impl-platform-adapter.md new file mode 100644 index 000000000..1b7b97634 --- /dev/null +++ b/docs/ja/workshop/impl-platform-adapter.md @@ -0,0 +1,50 @@ +# メッセージプラットフォームアダプターの実装 + +この記事では、`aiocqhttp`アダプターを例として、LangBotの新しいメッセージプラットフォームアダプターを実装し、WhatsAppやDiscordなどの新しいメッセージプラットフォームプロトコルを統合する方法を説明します。 + +## 登録 + +```text +新しいメッセージプラットフォームアダプターを追加します。例: WhatsApp、Discordなどを統合 + +- 基底クラス: `pkg.platform.adapter.MessageSourceAdapter` +- デコレーター: `pkg.platform.adapter.adapter_class(name: str)` +- 参考実装: `pkg.platform.sources/` +``` + +メッセージプラットフォームアダプターを実装するには、基本的に`基底クラス`を継承するクラスを実装し、`デコレーター`を使用して登録する必要があります。最後に、実行時にユーザーが選択して使用できるようになります。 + +### メインリポジトリへの貢献 + +`pkg/platform/sources/`ディレクトリに新しいファイル`aiocqhttp.py`を作成します: + +```python +from .. import adapter + +@adapter.adapter_class("aiocqhttp") +class AiocqhttpAdapter(adapter.MessageSourceAdapter): + pass +``` + +また、`pkg/platform/manager.py`の40行目でこのモジュールをインポートします: + +```python + from .sources import nakuru, aiocqhttp, qqbotpy +``` + +最後に、他のアダプターのマニフェストファイルを参考にして、独自のマニフェストファイルを作成します。 + +## イベントとメッセージコンバーター + +メッセージプラットフォームアダプターの主な作業は、`メッセージプラットフォームプロトコルからイベントを受信し、LangBotの形式に変換する`ことです。これをコアコンポーネントに渡し、LangBotのコアコンポーネントが処理した後、返信する必要のあるコンテンツをメッセージプラットフォームアダプターに渡します。次に、`コンテンツをプラットフォームプロトコル形式に変換してメッセージプラットフォームに送信します`。 + +次の図は、2つのシナリオの処理パターンを示しています: SDKのないメッセージプラットフォームプロトコルと成熟したSDKを持つプロトコル。最初のケースでは、メッセージプラットフォームプロトコルのドキュメントに従って、接続管理とネットワーク形式データのLBメッセージPythonオブジェクトへの変換を実装する必要があります。2番目のケースでは、メッセージプラットフォームに成熟したSDKがあり、SDKドキュメントに従って接続を作成し、イベントリスナーを登録し、メッセージコンバーターを実装するだけです。 + +![alt text](/assets/image/zh/workshop/impl-platform-adapter/workshop_impl_platform_adapter_01.png) + +`pkg.platform.sources.aiocqhttp`ファイルでは、`AiocqhttpAdapter`だけでなく、`class AiocqhttpMessageConverter(adapter.MessageConverter):`と`class AiocqhttpEventConverter(adapter.EventConverter):`も確認できます。 + +- `MessageConverter`は、LangBotメッセージとプラットフォームメッセージ間の変換に使用されます。 +- `EventConverter`は、LangBotイベントとプラットフォームイベント間の変換に使用されます。 + +TBC... diff --git a/docs/ja/workshop/mcp-details.md b/docs/ja/workshop/mcp-details.md new file mode 100644 index 000000000..f61a06fba --- /dev/null +++ b/docs/ja/workshop/mcp-details.md @@ -0,0 +1,25 @@ +# MCPエコシステムの詳細 + +[MCPプロトコル](https://modelcontextprotocol.io/)は、アプリケーションとLLM間のインタラクションを記述するプロトコルであり、さまざまな製品で採用されています。LangBotはMCPクライアントとして動作し、MCPサーバーに接続して、ユーザーとの会話中にLLMが使用する広範なツールを提供できます。 + +## MCPサーバーの検索 + +LangBotでMCPツールを使用するには、既存のMCPサーバーを見つけて接続する必要があります。 +市場には2種類のMCPサーバーがあります: + +- NodeまたはPythonで実装された実行可能ファイルで、`stdio`(標準入出力)を通じてLangBotと通信します +- HTTPプロトコルに基づくWebサービスで、HTTPプロトコルを通じてLangBotと通信します + +:::info + +- 既存のMCPサーバーは[MCPサーバーリスト](https://github.com/punkpeye/awesome-mcp-servers)で確認できます。 +- オンラインでホストされているMCPサーバーについては、[Composio MCP](https://mcp.composio.dev/)で見つけることができます。 +- 独自のMCPサーバーを作成するには、[MCPプロトコルドキュメント](https://modelcontextprotocol.io/quickstart/server)および[MCPサーバーの例](https://modelcontextprotocol.io/examples)を参照してください。 + +::: + +## MCPサーバーの設定 + +[システム設定ドキュメント](/en/deploy/settings.html)を参照してください + +設定後、チャットで`!func`コマンドを使用して、登録されたMCPツールを表示できます。Function Callingをサポートするモデルとチャットする際、LangBotは自動的にMCPツールを呼び出します。 diff --git a/docs/ja/workshop/network-details.md b/docs/ja/workshop/network-details.md new file mode 100644 index 000000000..c466b75ab --- /dev/null +++ b/docs/ja/workshop/network-details.md @@ -0,0 +1,62 @@ +# ネットワーク設定の詳細 + +::: info +一部のメッセージングプラットフォーム(個人QQアカウントなど)では、メッセージを処理するために独立したプロトコルエンドポイントが必要です。このようなメッセージングプラットフォームを使用している場合は、以下のネットワーク設定を参照してください。 +同時に、LangBotインスタンスがコンテナで実行されている他のサービス(Ollamaなど)に接続する必要がある場合も、以下の設定を参照して、`メッセージングプラットフォーム`を`接続したいサービス`に置き換えてください。 +::: + +LangBotと一部のメッセージングプラットフォームは、どちらもDockerを使用してデプロイできます。以下は、4つの異なるシナリオのネットワーク設定の詳細です。 + +:::info 目次 +[[toc]] +::: + +## LangBotとメッセージングプラットフォームの両方がDockerコンテナで実行されている場合 + +メッセージングプラットフォーム(NapCat/Lagrange)とLangBotの両方がDockerを使用して起動される場合、Dockerのネットワーク接続を設定する必要があります。 + +新しいネットワークを作成します: + +```bash +docker network create langbot-network +``` + +LangBotディレクトリの`docker-compose.yaml`ファイルにネットワーク設定を追加します(`services.langbot`フィールドに追加し、`networks`フィールドの下に`langbot-network`ネットワーク設定を追加します): + +```yaml +services: + langbot: + ... + networks: + - langbot-network + ... + +networks: + langbot-network: + external: true +``` + +次に、メッセージングプラットフォームの`docker-compose.yaml`ファイルに同じネットワーク設定を追加します(docker runコマンドで直接起動する場合は、起動コマンドに`--network langbot-network`を追加します)。その後、メッセージングプラットフォームの設定ファイルで、WSリバース接続アドレスのIPアドレスを`langbot`に変更します(例: `ws://langbot:2280/ws`)。 + +両方のコンテナを再起動します。 + + + +## LangBotのみがDockerコンテナで実行されている場合 + +LangBotのみがDockerを使用してデプロイされている場合、ポート2280から2290はデフォルトでコンテナの外部にマッピングされています。この場合、LangBotはWebSocketサーバーとしてのみ動作し、メッセージングプラットフォームからクライアントとしての接続を受け入れることができます。 + +メッセージングプラットフォームをReverseWebSocket(`reverse ws`または`WebSocketクライアント`と呼ばれます)に設定し、LangBotのaiocqhttpアダプターによって有効にされたポートに対応するポートで、ローカル127.0.0.1に接続します。 + + +## LangBotもメッセージングプラットフォームもDockerデプロイを使用していない場合 + +ドキュメントに従ってメッセージングプラットフォームとLangBotの設定を行い、両方のポートを同じ未使用のポートに設定し、両方ともローカル127.0.0.1に接続します。 + +## メッセージングプラットフォームのみがDockerコンテナで実行されている場合(推奨されません) + +:::warning +Linuxまたはホストモードのdockerネットワークをサポートする他のシステムのみサポートします。 +::: + +現在、LangBotのaiocqhttpアダプターはリバースWebSocket接続のみをサポートしています。メッセージングプラットフォームがDockerコンテナで実行され、LangBotがホストマシンで直接実行される場合、メッセージングプラットフォームはLangBotに接続するクライアントとして動作する必要があります。この場合、メッセージングプラットフォームのネットワークを`host`モードに設定し、そのWS接続アドレスを127.0.0.1に設定し、ポートをLangBotのaiocqhttpアダプターによって有効にされたポートに対応させることしかできません。 diff --git a/docs/ja/workshop/newapi-integration.md b/docs/ja/workshop/newapi-integration.md new file mode 100644 index 000000000..059db569c --- /dev/null +++ b/docs/ja/workshop/newapi-integration.md @@ -0,0 +1,44 @@ +# LangBotとNew APIの統合 + +New APIは次世代の大規模モデルゲートウェイおよびAI資産管理システムであり、複数のAIサービスプロバイダーへの断片的なアクセス、コスト管理の難しさ、サービス安定性の不足などの問題に対処するように設計されています。その中心的な利点は、次の3つの側面に焦点を当てています: + +1. **マルチプロバイダー互換性**: **30以上のAIサービスプロバイダー**を統合し、**100% OpenAI互換**を実現しています(つまり、OpenAIインターフェース形式で他のサービスプロバイダーのモデルを呼び出すことをサポートし、開発コストを削減します) +2. **高可用性**: **99.9%のサービス可用性**を約束し、エンタープライズレベルの安定性要件を満たします +3. **使いやすさと制御性**: 迅速なアクセスのための「ワンクリックデプロイ」をサポートし、ユーザーがAI使用コストを管理するのに役立つ「柔軟な請求」機能も提供し、「セキュリティと安定性」機能も考慮しています + +## 1. New APIをローカルにデプロイする(Dockerコンテナ方式) + +> その他のデプロイ方法については、[New APIデプロイガイド](https://docs.newapi.pro/installation/)を参照してください + +このデプロイ方法はSQLiteデータベースを使用します(軽量で、追加のデプロイは不要です)。 + +コマンドラインで次のように入力します: + +```bash +docker run --name new-api -d --restart always \ + -p 3000:3000 \ + -e TZ=Asia/Shanghai \ + -v ./new-api/data:/data \ + calciumion/new-api:latest +``` + +> ⚠️ 注意: +> - `./new-api/data`を使用したい実際のフォルダーに置き換えてください。 + +デプロイ後、`http://server-IP:3000`を開いてNew APIを設定します。 + +## 2. LangBotをローカルのNew APIに接続する + +1. **New APIモデルを追加** + - モデル名: New APIで設定されたモデル名を入力します + - モデルプロバイダー: New APIを選択します + - リクエストURL: `http://server-IP:3000/v1`を入力します + - APIキー: New APIで作成したトークンを入力します + +![](/assets/image/zh/workshop/newapi-integration/model.png) + +2. **パイプラインで新しく設定したモデルを選択** + +![](/assets/image/zh/workshop/newapi-integration/model2.png) + +3. これで、New APIのモデルを使用できます。 diff --git a/docs/ja/workshop/ppio-integration.md b/docs/ja/workshop/ppio-integration.md new file mode 100644 index 000000000..7079c5bef --- /dev/null +++ b/docs/ja/workshop/ppio-integration.md @@ -0,0 +1,5 @@ +# PPIO Cloud APIとのモデル統合 + +WebUIページを開き、モデルを追加する際に[PPIO Cloud](https://ppio.cn/user/register?from=ppinfra&invited_by=QJKFYD&utm_source=github_langbot)を選択します。 + +![model](/assets/image/zh/workshop/ppio-integration/model.png) diff --git a/docs/ja/workshop/production/proxy-and-ssl.md b/docs/ja/workshop/production/proxy-and-ssl.md new file mode 100644 index 000000000..0de0ffb9b --- /dev/null +++ b/docs/ja/workshop/production/proxy-and-ssl.md @@ -0,0 +1,125 @@ +# HTTPリバースプロキシの設定またはゲートウェイ経由でのLangBotへのアクセス + +LangBotにはHTTPSサービス用の組み込みSSLサポートがありません。ドメイン名をLangBotインスタンスに解決する必要がある場合、またはHTTPSを使用してLangBot WebUIとさまざまなボット用のWebhookアドレスにアクセスする必要がある場合は、このドキュメントを参照してNGINXまたはCaddyをデプロイし、HTTPリバースプロキシを実装してください。 + +公開IPアドレスを持つホストにLangBotをデプロイし、ドメイン名を購入し、ドメイン名をホストの公開IPに解決する必要があります。 + +::: warning +QQ公式ボット、WeChat公式アカウント、WeCom、Slack、LINEなどのWebhookコールバックアドレスが必要なボットを使用する必要がある場合は、このドキュメントに従ってHTTPリバースプロキシを設定する必要があります。 +::: + +## Caddy + +Caddyは、自動HTTPS証明書申請と更新、リバースプロキシ、自動DNS解決設定をサポートする最新のHTTPサーバーです。 + +[Caddyインストールドキュメント](https://caddy2.dengxiaolong.com/docs/install)。お使いのオペレーティングシステムに対応するインストール手順を選択して、インストールを進めてください。 + +### Caddyfileの設定 + +このドキュメントでは、LangBotをデプロイするためにUbuntuシステムを使用することを前提としています。システムでは、Caddyfileのデフォルトの場所は`/etc/caddy/Caddyfile`です。 +vimまたはnanoを使用してCaddyfileを編集し、次のようにCaddyfileに記入します: + +```json +your.domain.com { + reverse_proxy 127.0.0.1:5300 +} +``` + +::: info +CaddyとLangBotがコンテナを使用してデプロイされている場合は、[コンテナネットワーク設定の詳細](/en/workshop/network-details)を確認してください +::: + +これで、ブラウザを通じて`https://your.domain.com`でLangBot WebUIにアクセスできます。 + +### ボットコールバックアドレスプレフィックスの設定 + +QQ公式ボット、WeChat公式アカウント、WeCom、Slack、LINEなどのWebhookコールバックアドレスが必要なボットを使用する必要がある場合は、data/config.yamlファイルで`api.webhook_prefix`をドメイン名に設定してください。例: `https://your.domain.com`。 + +その後、ボット管理ページに正しく表示されたコールバックアドレスが表示されます。 + +## NGINX + +NGINXも一般的に使用されるHTTPサーバーおよびリバースプロキシツールであり、LangBotへのHTTPSアクセスを実装するために使用できます。 + +### NGINXのインストール + +Ubuntuでは、次のコマンドでNGINXをインストールできます: + +```bash +sudo apt update +sudo apt install nginx +``` + +### SSL証明書の準備 + +[Let's Encrypt](https://letsencrypt.org/)を使用して無料のSSL証明書を申請できます。証明書を取得するには、[Certbot](https://certbot.eff.org/)ツールの使用をお勧めします: + +```bash +sudo apt install certbot python3-certbot-nginx +sudo certbot --nginx +``` + +プロンプトに従ってドメイン名を入力すると、証明書の申請とNGINXの設定が自動的に完了します。以下の内容を参照してNGINX設定を完了してください。 + +### NGINXリバースプロキシの設定 + +LangBotのパイプラインデバッグ機能では、WebSocket接続を使用する必要があるため、NGINXをWebSocketをサポートするように設定する必要があります。 + +NGINX設定ファイル`/etc/nginx/sites-available/langbot`を編集します(vimまたはnanoエディターを使用できます): + +```nginx +# WebSocket接続アップグレードマッピング(serverブロックの外側に配置) +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 80; + server_name your.domain.com; + # HTTPトラフィックをHTTPSにリダイレクト + return 301 https://$host$request_uri; +} + +server { + listen 443 ssl; + server_name your.domain.com; + + ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + # LangBotインスタンスへのリバースプロキシ + location / { + proxy_pass http://127.0.0.1:5300; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocketサポート + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_read_timeout 86400; + } +} +``` + +`your.domain.com`を実際のドメイン名に置き換えてください。 + +この設定を有効にし、NGINXを再起動します: + +```bash +sudo ln -s /etc/nginx/sites-available/langbot /etc/nginx/sites-enabled/langbot +sudo nginx -t +sudo systemctl reload nginx +``` + +### ボットコールバックアドレスプレフィックスの設定 + +同様に、`data/config.yaml`設定ファイルで`api.webhook_prefix`を`https://your.domain.com`に設定すると、ボットWebhookコールバックアドレスが正しくなります。 + +上記の設定を完了すると、`https://your.domain.com`を通じてLangBot WebUIとボットWebhookサービスに安全にアクセスできます。