diff --git a/docs/css/extra.css b/docs/css/extra.css index 48d0bac42..a816ad48b 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -1,6 +1,12 @@ /* =============================== 自定义进度条 =============================== */ +/* 所有图片 */ +.md-content img { + border-radius: 0 0 10px 10px; + box-shadow: 0 2px 8px rgba(0,0,0,0.1); +} + .progress { display: block; @@ -64,19 +70,20 @@ display: block; border: none; border-radius: 4px; - box-shadow: 0 0.1em .5em 0 rgba(0, 0, 0, 0.4); + box-shadow: 0 0.1em .5em 0 rgba(124, 83, 83, 0.4); } /* 浏览器 mockup 布局样式 */ .browser-mockup { position: relative; max-width: 1200px; - margin: 0 auto; + margin: 5 auto; border-top: 2em solid rgba(230, 230, 230, 0.8); - border-radius: 4px 4px 4px 4px; + border-radius: 10px; box-shadow: 0 0.1em .5em 0 rgba(0, 0, 0, 0.4); } + .browser-mockup:before { display: block; position: absolute; diff --git a/docs/img/ai/ai_benchmark_create.png b/docs/img/ai/ai_benchmark_create.png new file mode 100644 index 000000000..6b8b90202 Binary files /dev/null and b/docs/img/ai/ai_benchmark_create.png differ diff --git a/docs/img/ai/ai_benchmark_detail.png b/docs/img/ai/ai_benchmark_detail.png new file mode 100644 index 000000000..120059a4d Binary files /dev/null and b/docs/img/ai/ai_benchmark_detail.png differ diff --git a/docs/img/ai/ai_benchmark_list.png b/docs/img/ai/ai_benchmark_list.png new file mode 100644 index 000000000..e82219ca8 Binary files /dev/null and b/docs/img/ai/ai_benchmark_list.png differ diff --git a/docs/img/ai/ai_benchmark_task_detail.png b/docs/img/ai/ai_benchmark_task_detail.png new file mode 100644 index 000000000..e12be2d78 Binary files /dev/null and b/docs/img/ai/ai_benchmark_task_detail.png differ diff --git a/docs/img/ai/ai_benchmark_task_detail_button.png b/docs/img/ai/ai_benchmark_task_detail_button.png new file mode 100644 index 000000000..a659fdb44 Binary files /dev/null and b/docs/img/ai/ai_benchmark_task_detail_button.png differ diff --git a/docs/img/ai/ai_gateway_account_pool.png b/docs/img/ai/ai_gateway_account_pool.png new file mode 100644 index 000000000..81f9ec7c7 Binary files /dev/null and b/docs/img/ai/ai_gateway_account_pool.png differ diff --git a/docs/img/ai/ai_gateway_api_key_create.png b/docs/img/ai/ai_gateway_api_key_create.png new file mode 100644 index 000000000..53793fe1e Binary files /dev/null and b/docs/img/ai/ai_gateway_api_key_create.png differ diff --git a/docs/img/ai/ai_gateway_compliance.png b/docs/img/ai/ai_gateway_compliance.png new file mode 100644 index 000000000..b84b9f51d Binary files /dev/null and b/docs/img/ai/ai_gateway_compliance.png differ diff --git a/docs/img/ai/ai_gateway_compliance_Log.png b/docs/img/ai/ai_gateway_compliance_Log.png new file mode 100644 index 000000000..da310d983 Binary files /dev/null and b/docs/img/ai/ai_gateway_compliance_Log.png differ diff --git a/docs/img/ai/ai_gateway_compliance_apifox.png b/docs/img/ai/ai_gateway_compliance_apifox.png new file mode 100644 index 000000000..1604293e0 Binary files /dev/null and b/docs/img/ai/ai_gateway_compliance_apifox.png differ diff --git a/docs/img/ai/ai_gateway_compliance_fenzu.png b/docs/img/ai/ai_gateway_compliance_fenzu.png new file mode 100644 index 000000000..ff68d7548 Binary files /dev/null and b/docs/img/ai/ai_gateway_compliance_fenzu.png differ diff --git a/docs/img/ai/ai_gateway_compliance_shenheyangben.png b/docs/img/ai/ai_gateway_compliance_shenheyangben.png new file mode 100644 index 000000000..26a6e4ae9 Binary files /dev/null and b/docs/img/ai/ai_gateway_compliance_shenheyangben.png differ diff --git a/docs/img/ai/ai_gateway_embedding_model_download.png b/docs/img/ai/ai_gateway_embedding_model_download.png new file mode 100644 index 000000000..c3f3f8cd3 Binary files /dev/null and b/docs/img/ai/ai_gateway_embedding_model_download.png differ diff --git a/docs/img/ai/ai_gateway_embedding_settings.png b/docs/img/ai/ai_gateway_embedding_settings.png new file mode 100644 index 000000000..9fb39a827 Binary files /dev/null and b/docs/img/ai/ai_gateway_embedding_settings.png differ diff --git a/docs/img/ai/ai_gateway_import_account.png b/docs/img/ai/ai_gateway_import_account.png new file mode 100644 index 000000000..0e6910f1a Binary files /dev/null and b/docs/img/ai/ai_gateway_import_account.png differ diff --git a/docs/img/ai/ai_gateway_model_groups.png b/docs/img/ai/ai_gateway_model_groups.png new file mode 100644 index 000000000..ca2b56c65 Binary files /dev/null and b/docs/img/ai/ai_gateway_model_groups.png differ diff --git a/docs/img/ai/ai_gateway_settings_basic.png b/docs/img/ai/ai_gateway_settings_basic.png new file mode 100644 index 000000000..a8e5517bf Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_basic.png differ diff --git a/docs/img/ai/ai_gateway_settings_elasticsearch.png b/docs/img/ai/ai_gateway_settings_elasticsearch.png new file mode 100644 index 000000000..fd2cdb054 Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_elasticsearch.png differ diff --git a/docs/img/ai/ai_gateway_settings_info.png b/docs/img/ai/ai_gateway_settings_info.png new file mode 100644 index 000000000..aac725fde Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_info.png differ diff --git a/docs/img/ai/ai_gateway_settings_logsetting.png b/docs/img/ai/ai_gateway_settings_logsetting.png new file mode 100644 index 000000000..60acfea5c Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_logsetting.png differ diff --git a/docs/img/ai/ai_gateway_settings_performance.png b/docs/img/ai/ai_gateway_settings_performance.png new file mode 100644 index 000000000..64183faf4 Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_performance.png differ diff --git a/docs/img/ai/ai_gateway_settings_smart_routing.png b/docs/img/ai/ai_gateway_settings_smart_routing.png new file mode 100644 index 000000000..9be027276 Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_smart_routing.png differ diff --git a/docs/img/ai/ai_gateway_settings_smart_routing_setCompliance.png b/docs/img/ai/ai_gateway_settings_smart_routing_setCompliance.png new file mode 100644 index 000000000..a04842634 Binary files /dev/null and b/docs/img/ai/ai_gateway_settings_smart_routing_setCompliance.png differ diff --git a/docs/img/ai/ai_gateway_smart_routing.png b/docs/img/ai/ai_gateway_smart_routing.png new file mode 100644 index 000000000..1f094287f Binary files /dev/null and b/docs/img/ai/ai_gateway_smart_routing.png differ diff --git a/docs/img/ai/ai_gateway_smart_routing_sample.png b/docs/img/ai/ai_gateway_smart_routing_sample.png new file mode 100644 index 000000000..b3156cfca Binary files /dev/null and b/docs/img/ai/ai_gateway_smart_routing_sample.png differ diff --git a/docs/img/ai/ai_gateway_smart_routing_sample_juece.png b/docs/img/ai/ai_gateway_smart_routing_sample_juece.png new file mode 100644 index 000000000..25f50f3e2 Binary files /dev/null and b/docs/img/ai/ai_gateway_smart_routing_sample_juece.png differ diff --git a/docs/img/ai/ai_gateway_smart_routing_sample_tongji.png b/docs/img/ai/ai_gateway_smart_routing_sample_tongji.png new file mode 100644 index 000000000..62b41ec96 Binary files /dev/null and b/docs/img/ai/ai_gateway_smart_routing_sample_tongji.png differ diff --git a/docs/img/ai/ai_gateway_smart_routing_sample_yulan.png b/docs/img/ai/ai_gateway_smart_routing_sample_yulan.png new file mode 100644 index 000000000..40c3efd3b Binary files /dev/null and b/docs/img/ai/ai_gateway_smart_routing_sample_yulan.png differ diff --git a/docs/img/ai/ai_gateway_usage_new_fenbu.png b/docs/img/ai/ai_gateway_usage_new_fenbu.png new file mode 100644 index 000000000..4662deec3 Binary files /dev/null and b/docs/img/ai/ai_gateway_usage_new_fenbu.png differ diff --git a/docs/img/ai/ai_gateway_usage_new_log.png b/docs/img/ai/ai_gateway_usage_new_log.png new file mode 100644 index 000000000..64d80a3ce Binary files /dev/null and b/docs/img/ai/ai_gateway_usage_new_log.png differ diff --git a/docs/img/ai/ai_gateway_usage_new_ranking.png b/docs/img/ai/ai_gateway_usage_new_ranking.png new file mode 100644 index 000000000..7d85662ae Binary files /dev/null and b/docs/img/ai/ai_gateway_usage_new_ranking.png differ diff --git a/docs/img/ai/ai_gateway_user_groups.png b/docs/img/ai/ai_gateway_user_groups.png new file mode 100644 index 000000000..3cc4395bb Binary files /dev/null and b/docs/img/ai/ai_gateway_user_groups.png differ diff --git a/docs/img/ai/skills_hub_import_detail.png b/docs/img/ai/skills_hub_import_detail.png new file mode 100644 index 000000000..9248d784c Binary files /dev/null and b/docs/img/ai/skills_hub_import_detail.png differ diff --git a/docs/img/ai/skills_hub_import_github.png b/docs/img/ai/skills_hub_import_github.png new file mode 100644 index 000000000..c43788801 Binary files /dev/null and b/docs/img/ai/skills_hub_import_github.png differ diff --git a/docs/img/ai/skills_hub_import_url.png b/docs/img/ai/skills_hub_import_url.png new file mode 100644 index 000000000..b8b64102c Binary files /dev/null and b/docs/img/ai/skills_hub_import_url.png differ diff --git a/docs/img/ai/skills_hub_list_pending.png b/docs/img/ai/skills_hub_list_pending.png new file mode 100644 index 000000000..e90234a85 Binary files /dev/null and b/docs/img/ai/skills_hub_list_pending.png differ diff --git a/docs/img/ai/skills_hub_targets.png b/docs/img/ai/skills_hub_targets.png new file mode 100644 index 000000000..deba18a24 Binary files /dev/null and b/docs/img/ai/skills_hub_targets.png differ diff --git a/docs/img/ai/skills_hub_targets_button.png b/docs/img/ai/skills_hub_targets_button.png new file mode 100644 index 000000000..a8a4c95bf Binary files /dev/null and b/docs/img/ai/skills_hub_targets_button.png differ diff --git a/docs/img/ai/skills_hub_upload.png b/docs/img/ai/skills_hub_upload.png new file mode 100644 index 000000000..63a335dca Binary files /dev/null and b/docs/img/ai/skills_hub_upload.png differ diff --git a/docs/img/ai/vllm_create.png b/docs/img/ai/vllm_create.png new file mode 100644 index 000000000..9606e2b4c Binary files /dev/null and b/docs/img/ai/vllm_create.png differ diff --git a/docs/img/app/Hermes_Agent_index.png b/docs/img/app/Hermes_Agent_index.png new file mode 100644 index 000000000..0faac62bd Binary files /dev/null and b/docs/img/app/Hermes_Agent_index.png differ diff --git a/docs/img/app/Hermes_Agent_install.png b/docs/img/app/Hermes_Agent_install.png new file mode 100644 index 000000000..d60a5c0d6 Binary files /dev/null and b/docs/img/app/Hermes_Agent_install.png differ diff --git a/docs/img/app/deepseek-harness-api-key.png b/docs/img/app/deepseek-harness-api-key.png new file mode 100644 index 000000000..fb916590d Binary files /dev/null and b/docs/img/app/deepseek-harness-api-key.png differ diff --git a/docs/img/app/deepseek-harness-install.png b/docs/img/app/deepseek-harness-install.png new file mode 100644 index 000000000..25f25c3ee Binary files /dev/null and b/docs/img/app/deepseek-harness-install.png differ diff --git a/docs/img/app/deepseek-harness-provider.png b/docs/img/app/deepseek-harness-provider.png new file mode 100644 index 000000000..ed8c99dd5 Binary files /dev/null and b/docs/img/app/deepseek-harness-provider.png differ diff --git a/docs/img/app/deepseek-harness-search.png b/docs/img/app/deepseek-harness-search.png new file mode 100644 index 000000000..7e9de7f0f Binary files /dev/null and b/docs/img/app/deepseek-harness-search.png differ diff --git a/docs/img/app/deepseek-harness-task.png b/docs/img/app/deepseek-harness-task.png new file mode 100644 index 000000000..5d3a0efdf Binary files /dev/null and b/docs/img/app/deepseek-harness-task.png differ diff --git a/docs/user_manual/ai/agent.md b/docs/user_manual/ai/agent.md index fc83eb0fa..fff6ff8f2 100644 --- a/docs/user_manual/ai/agent.md +++ b/docs/user_manual/ai/agent.md @@ -202,7 +202,6 @@ The operation page is shown in the figure below. ![img.png](../../img/ai/Discord_Developer_Mode_Page.png) - {: .browser-mockup} ### 4.5. Step 5: Configure OpenClaw for Discord Channel @@ -304,7 +303,6 @@ After completing the configuration, enter the "Configuration" page of "Agent" in 1Panel, complete the Discord chat channel configuration, and click "Save", as shown in the figure below: ![img.png](../../img/ai/1Panel_OpenClaw_Discord_Channel_Config.png) - {: .browser-mockup} ### 4.6. Step 6: Start Gateway and Verify Configuration @@ -326,7 +324,6 @@ - 3. If the bot replies normally, it indicates that the configuration is successful. The test effect is shown in the figure below. ![img.png](../../img/ai/Discord_OpenClaw_Bot_Test_Page.png) - {: .browser-mockup} ### 4.7. Step 7: Troubleshooting (Common Issues) diff --git a/docs/user_manual/ai/benchmark.md b/docs/user_manual/ai/benchmark.md new file mode 100644 index 000000000..a1fbbabbc --- /dev/null +++ b/docs/user_manual/ai/benchmark.md @@ -0,0 +1,104 @@ +# Benchmark Testing + +!!! note "" + Benchmark testing is used to perform stress testing on OpenAI-compatible large language model services, helping to evaluate the model's throughput and latency performance under a specified context length, concurrency level, and request rate. + + After entering the 1Panel dashboard, open the **AI -> Benchmark Testing** page to manage it. + + This feature belongs to [1Panel Enterprise Edition](https://1panel.cn/enterprise.html). + +![Benchmark Testing](../../img/ai/ai_benchmark_list.png) +{: .browser-mockup} + +## 1 Prerequisites + +!!! note "" + Before creating a benchmark test, please confirm the following conditions: + + - An accessible OpenAI-compatible endpoint has been prepared, such as an AI Gateway, vLLM, Ollama, or other compatible service + - A valid API Key has been prepared. If the target service does not require authentication, leave it blank or fill in a placeholder value as required by the page + - The name of the model to be tested has been confirmed + - A local tokenizer directory has been prepared for generating test data based on the target number of tokens + - The server can normally pull or use the vLLM image configured on the page + +> If you need to test an AI Gateway, first create an API Key under **AI -> AI Gateway**, and use the external access address as the service address of the benchmark test. + +## 2 Creating a Test Task + +!!! note "" + Click **Create**, fill in parameters such as the service address, endpoint path, API Key, model, tokenizer directory, input/output tokens, request count, and concurrency, then click **Confirm** to create the task. + + After the task is successfully created, the system will start a background task to execute the benchmark test, and the execution process can be viewed through the task log. + +![Create Benchmark Test](../../img/ai/ai_benchmark_create.png) +{: .browser-mockup} + +!!! info "Basic Parameters" + - **Service Address**: The address of the target model service, e.g., `http://127.0.0.1:4000` + - **Endpoint Path**: The OpenAI-compatible endpoint path, defaulting to `/v1/chat/completions` + - **API Key**: The access credential of the target service + - **Model**: The name of the model to be tested + - **Tokenizer**: The local tokenizer directory on the server, e.g., `/opt/1panel/tokenizers/DeepSeek-V3` + +!!! info "Stress Testing Parameters" + - **Input Tokens**: The number of input tokens per request + - **Output Tokens**: The upper limit of output tokens per request + - **Request Count**: The total number of requests sent in this test + - **Concurrency**: The number of requests initiated simultaneously + - **Request Rate**: Limits the number of requests per second; when no rate limit is selected, the throughput of the target service will be saturated as much as possible + - **Timeout**: The maximum time allowed for a single task to execute + - **vLLM Image**: The image used when executing the benchmark test + - **Ignore EOS**: When enabled, the model will generate up to the configured number of output tokens, facilitating stable throughput comparison + - **Extra Request Headers**: Appends request headers in JSON format, e.g., `{"X-Request-Source":"1Panel"}` + +## 3 Viewing Test Results + +!!! note "" + After a test task is completed, you can view the model, context length, output throughput, total throughput, time to first token, status, and creation time in the list. + + Click the task name to open the details drawer and view the basic information, runtime configuration, result metrics, startup command, and raw results. + +![Benchmark Test Details](../../img/ai/ai_benchmark_detail.png) +{: .browser-mockup} + + + +!!! info "Core Metrics" + - **Context Length**: The sum of the input token upper limit and the output token upper limit + - **Output Throughput**: The number of output tokens generated by the model per second; a higher value indicates faster generation speed + - **Total Throughput**: The total number of input and output tokens processed per second + - **Time to First Token (TTFT)**: The time from when a request is sent to when the first token is received; a lower value indicates a faster response + - **Request Throughput**: The number of requests completed per second + - **TPOT**: The average generation time of each output token + - **ITL**: The average interval between output tokens + - **Successful / Failed Requests**: The number of successful and failed requests in this test + +> Because different test tasks use different input/output tokens, concurrency, request rates, network environments, and backend models, metrics should not be directly mixed for comparison. It is recommended to fix the test parameters before comparing different models or different deployment methods. + +## 4 Task Operations + +!!! note "" + In the task list, you can perform operations such as viewing logs, re-testing, canceling, and deleting test tasks. + + - **Log**: Views the task execution log, suitable for troubleshooting image pulls, connection failures, or parameter errors + - **Re-test**: Creates a new test task using the parameters of an existing task + - **Cancel**: When a task is running or waiting, you can cancel its execution + - **Delete**: Deletes test records that are no longer needed +![alt text](../../img/ai/ai_benchmark_task_detail_button.png) +{: .browser-mockup} + + +![Benchmark Test Details](../../img/ai/ai_benchmark_task_detail.png) +{: .browser-mockup} + + +## 5 General Recommendations + +!!! note "" + To obtain more stable test results, it is recommended to: + + - Execute tests when the server load is low + - Use the same input/output tokens, concurrency, and request rate for horizontal comparison + - Run multiple rounds of tests for the same model and focus on the average performance rather than a single result + - When testing an AI Gateway, analyze it together with the AI Gateway's usage statistics and call logs + - When testing a local GPU inference service, observe changes in VRAM usage, utilization, and temperature in conjunction with GPU monitoring diff --git a/docs/user_manual/ai/gateway.md b/docs/user_manual/ai/gateway.md new file mode 100644 index 000000000..5527279f4 --- /dev/null +++ b/docs/user_manual/ai/gateway.md @@ -0,0 +1,324 @@ +# AI Gateway + +!!! note "" + The AI Gateway is used to centrally manage model accounts, access credentials, access quotas, and request forwarding. Clients only need to configure the gateway's external connection address and API Key to call models from different providers or models deployed locally through a unified entry point. + + After entering the 1Panel dashboard, open the **AI -> AI Gateway** page to manage it. + + This feature belongs to [1Panel Enterprise Edition](https://1panel.cn/enterprise.html). + +!!! note "" + The new version of the AI Gateway includes 8 functional entry points: **Account Pool, Model Group, API Key, User Group, Smart Routing, Content Compliance, Usage Statistics, and Settings**. It is recommended to complete the initial configuration in the following order: + + +!!! note "" + 1. Import model accounts in the **Account Pool** and configure model mappings. + 2. Create **Model Groups** as needed to restrict the models available to user groups or configure smart routing. + 3. Create **User Groups**, and set the QPS, token quota, and model scope. + 4. Create an **API Key** to deliver to clients for use. + 5. Enable smart routing, content compliance, usage statistics, and Elasticsearch as needed. + +## 1 Runtime Status and Basic Operations + +!!! note "" + The top of the AI Gateway page displays the service status and external connection address, and provides the following operations: + + - **Status**: Displays the runtime status, service auto-start, listening port, load balancing policy, concurrency limit, timeout parameters, log path, and Elasticsearch write status + - **Start / Stop / Restart**: Controls the AI Gateway service + - **Settings**: Opens the gateway settings page + - **Log**: Views the AI Gateway runtime logs + - **External Connection Address**: The Base URL configured on the client side, which can be copied directly + +![alt text](../../img/ai/ai_gateway_settings_info.png) +{: .browser-mockup} + + + +## 2 Account Pool + +!!! note "" + The **Account Pool** is used to maintain the upstream model accounts of the AI Gateway. Click **Import Model Account**, select an account created under **AI -> Model**, and configure the weight, priority, and model mapping. + + The list displays the model provider, API type, upstream API address, health status, failure count, and latest error, making it easy to verify whether an account can participate normally in forwarding. The current page can simultaneously manage model accounts of different API types such as `openai-completions`, `openai-responses`, and `anthropic-messages`. + +![AI Gateway Account Pool](../../img/ai/ai_gateway_account_pool.png) +{: .browser-mockup} + +!!! info "Import Parameters" + - **Model Account**: Select an existing model account + - **Weight**: When the load balancing policy uses weight, a higher weight means the account undertakes more requests + - **Priority**: When the load balancing policy uses priority, the value is used to determine the account selection order + - **Model Mapping**: Maps the model requested by the client to the real upstream model of this account + - **Verify Account Availability**: Sends a minimal request before saving to check whether the endpoint is available + - **Enabled**: Controls whether this account participates in gateway forwarding + +![Import Model Account](../../img/ai/ai_gateway_import_account.png) +{: .browser-mockup} + +> On the left side of the model mapping, enter the `model` in the client request, and on the right side, enter the real upstream model. The client only needs to be aware of the requested model name after mapping. + +## 3 Model Group + +!!! note "" + A **Model Group** is used to combine a set of real upstream models, primarily applied to user group model permissions and smart routing. When creating a model group, fill in the name, requested model, and remarks; the order of models within the group represents the selection priority of smart routing, and load balancing is not performed among models within the group. + + `auto` is the virtual model name used by clients to trigger smart routing and does not need to be added to a model group. + +![AI Gateway Model Group](../../img/ai/ai_gateway_model_groups.png) +{: .browser-mockup} + +## 4 User Group + +!!! note "" + A **User Group** is used to centrally manage the call quotas and model scope of a set of API Keys. After creating a user group, bind the API Keys to that user group. + +![AI Gateway User Group](../../img/ai/ai_gateway_user_groups.png) +{: .browser-mockup} + +!!! info "User Group Parameters" + - **User Group**: The name of the user group + - **QPS Limit**: Limits the number of requests per second; `0` means no limit + - **Token Limit**: Limits the token quota available to this group; `0` means no limit + - **Model Group**: Restricts the models that this group can call; when not selected, it means no restriction + - **Status**: When disabled, the API Keys under this group can no longer make calls + - **Remarks**: Records the department, project, or usage scenario + +> The default user group cannot be deleted. After an API Key is bound to a user group, it inherits the user group's QPS, token quota, and model scope. + +## 5 API Key + +!!! note "" + On the **API Key** page, click **Create**, select the user and user group, confirm the API Key generated by the system, and save. The list displays information such as the available models, QPS limit, token usage, status, and last used time, and supports editing, deleting, and resetting the token. + + The API Key is only fully displayed at the time of creation, so be sure to save it properly. After resetting the token, the original token can no longer be used, and the client configuration must be updated accordingly. + +![Create API Key](../../img/ai/ai_gateway_api_key_create.png) +{: .browser-mockup} + +!!! info "Client Call Example" + ```bash + curl http://:4000/v1/chat/completions \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "model": "deepseek-v4-flash", + "messages": [ + { + "role": "user", + "content": "Hello" + } + ], + "stream": true + }' + ``` +> Clients should use the **external connection address** at the top of the page as the Base URL. `model` can be filled with the requested model name in the account pool; after enabling smart routing, `auto` can also be filled in. + +## 6 Smart Routing + +!!! note "" + Smart routing selects a model between a simple model group and a complex model group based on request complexity. Smart routing is only triggered when the client request uses `model=auto`; when other model names are requested, the request is forwarded through the normal AI Gateway flow. + +![AI Gateway Smart Routing](../../img/ai/ai_gateway_smart_routing.png) +{: .browser-mockup} + +### 6.1 Configuration Process + +!!! note "" + 1. In **Model Group**, create a simple model group and a complex model group respectively, and configure the real upstream models. + 2. In **Settings -> Embedding**, configure the Embedding service, routing threshold, and TopK. + 3. In **Settings -> Smart Routing**, enable the feature and select the simple model group and complex model group. + 4. In **Smart Routing -> Samples**, maintain simple and complex request samples, and generate or rebuild vectors. + 5. The client initiates a request using `model=auto`. + +### 6.2 Feature Description + +!!! info "Samples" + Samples are used to describe simple or complex questions. The list displays the label, sample text, vector model, and vector dimension. After adding or adjusting the Embedding configuration, you can click **Rebuild Vectors**. + +![Smart Routing Sample](../../img/ai/ai_gateway_smart_routing_sample.png) +{: .browser-mockup} + +!!! info "Preview" + Enter a piece of request text to see whether it will be judged as simple or complex, and the source of the judgment is displayed. The preview only executes the routing judgment and does not actually call the upstream model. + +![Smart Routing Preview](../../img/ai/ai_gateway_smart_routing_sample_yulan.png) +{: .browser-mockup} + +!!! info "Decision Log" + Records the request ID, judgment label, final model, judgment source, confidence, duration, and creation time. The judgment source includes sample matching and rule judgment, and you can jump to the corresponding call log. + +![Smart Routing Decision](../../img/ai/ai_gateway_smart_routing_sample_juece.png) +{: .browser-mockup} + +!!! info "Statistics" + Displays the proportion of simple/complex requests, sample match proportion, total tokens, average tokens, failed requests, and the distribution by label, source, model, and token. + +![Smart Routing Statistics](../../img/ai/ai_gateway_smart_routing_sample_tongji.png) +{: .browser-mockup} + +## 7 Content Compliance + +!!! note "" + Content compliance supports sensitive word matching and semantic review samples based on Embedding. Before enabling it, you first need to turn on the master switch in **Settings -> Content Compliance**; when using review samples, you also need to complete the configuration of **Settings -> Embedding**. + +!!! info "Sensitive Words" + Supports creating and batch importing sensitive words, and setting sensitive word groups, normalized words, status, and remarks. Normalized words are used to unify different spellings into a single matching word. + +![AI Gateway Content Compliance](../../img/ai/ai_gateway_compliance.png) +{: .browser-mockup} + +!!! info "Sensitive Word Group" + Sets the action, risk level, status, and description for a group of sensitive words. The action includes **Block** and **Log Only**. + +![AI Gateway Sensitive Word Group](../../img/ai/ai_gateway_compliance_fenzu.png) +{: .browser-mockup} + +!!! info "Review Samples" + Maintains the review text used for semantic matching and sets labels. The list displays the vector model and dimension. After sample changes or Embedding configuration adjustments, vectors can be rebuilt. + +![AI Gateway Review Sample](../../img/ai/ai_gateway_compliance_shenheyangben.png) +{: .browser-mockup} + +!!! info "Audit Log" + Records the Request ID, requested model, matched word, matched group, action, status code, and creation time, for tracking requests that were logged or blocked. + +![AI Gateway Review Sample](../../img/ai/ai_gateway_compliance_apifox.png) +{: .browser-mockup} + +![AI Gateway Review Sample](../../img/ai/ai_gateway_compliance_Log.png) +{: .browser-mockup} + +## 8 Usage Statistics + +!!! note "" + **Usage Statistics** provides 3 views: Distribution, Leaderboard, and Call Log, and supports filtering by user, model provider, model, and keyword. + +!!! info "Distribution" + Provides statistics on the request count, token usage, cached tokens, and proportion by model provider, model, model account, user group, and user. + +![AI Gateway Usage Distribution](../../img/ai/ai_gateway_usage_new_fenbu.png) +{: .browser-mockup} + +!!! info "Leaderboard" + Displays the request count, input tokens, output tokens, total tokens, and cached tokens by user, and supports sorting by metric. + +![AI Gateway Usage Leaderboard](../../img/ai/ai_gateway_usage_new_ranking.png) +{: .browser-mockup} + +!!! info "Call Log" + Displays the Request ID, model provider, requested model, upstream model, user, user group, input/output/total tokens, cached tokens, status code, response time, and request time. Click **Details** to view the information of a single call. + +![AI Gateway Call Log](../../img/ai/ai_gateway_usage_new_log.png) +{: .browser-mockup} + +## 9 Gateway Settings + +### 9.1 Basic Settings + +!!! note "" + **Basic Settings** is used to control the gateway switch, listening port, external connection address, and load balancing policy. The external connection address should be the address actually accessible to clients and must contain the `/v1` path. + +![AI Gateway Basic Settings](../../img/ai/ai_gateway_settings_basic.png) +{: .browser-mockup} + +### 9.2 Performance Settings + +!!! info "Parameter Description" + - **Maximum Concurrency**: The maximum number of requests processed simultaneously + - **Waiting Queue Size**: The number of requests allowed to queue after the concurrency limit is exceeded + - **Queue Wait Timeout**: The maximum waiting time of a request in the queue + - **Non-streaming Request Timeout**: The maximum execution time of a normal request + - **Streaming Idle Timeout**: The maximum waiting time when a streaming response returns no data + - **Maximum Request Body**: The size limit of a single request body + - **Runtime Refresh Interval**: The refresh interval of the runtime configuration + +![AI Gateway Performance Settings](../../img/ai/ai_gateway_settings_performance.png) +{: .browser-mockup} + +### 9.3 Embedding Settings + +!!! note "" + The Embedding service is used for semantic matching of both smart routing samples and content compliance review samples. The page supports configuring the service address, model, and API Key, and provides a connection test. + +#### 9.3.1 Deploying the Embedding Model +!!! note "" + 1. Enter **AI -> Model -> Downloader**, download the `Qwen3-Embedding-0.6B-GGUF` model, and confirm that the model files contain `qwen3-embedding-0.6b-q8_0.gguf`. + 2. Enter the **App Store**, search for and install `llama.cpp`. + 3. In the installation parameters, set the **Model Directory** to: + + ```text + /opt/1panel/ai/models + ``` + + 4. Set the **Startup Parameters** to: + + ```text + -m /models/Qwen3-Embedding-0.6B-GGUF/qwen3-embedding-0.6b-q8_0.gguf --host 0.0.0.0 --port 8080 --embedding --pooling last -c 32768 + ``` + + 5. Complete the installation and confirm that the `llama.cpp` application is in the running state. + +> The **Model Directory** is `/opt/1panel/ai/models` on the host machine. This directory is mounted as `/models` inside the `llama.cpp` container, so the model path in the startup parameters must begin with `/models`. + +#### 9.3.2 Connecting to the AI Gateway +!!! note "" + Enter **AI -> AI Gateway -> Settings -> Embedding**, and fill in the following parameters: + +!!! info "Connection Parameters" + - **Address**: `http://127.0.0.1:8080` + - **Model**: `Qwen3-Embedding-0.6B` + - **API Key**: Leave blank when the local `llama.cpp` does not have authentication configured + +![AI Gateway Embedding Settings](../../img/ai/ai_gateway_embedding_settings.png) +{: .browser-mockup} + +!!! note "" + Click **Connection Test**. After the test succeeds, save the configuration, and then generate or rebuild vectors on the smart routing sample or content review sample page. + +!!! info "Decision Parameters" + - **Routing Threshold**: The sample match result is adopted only when the similarity between the request and the smart routing samples reaches this value + - **Review Threshold**: The request is considered to match a review sample only when its similarity to the content review samples reaches this value + - **TopK**: The number of most similar samples involved in each judgment + +> After modifying the Embedding address, model, or decision parameters, you should return to the smart routing sample and content review sample pages to rebuild the vectors. + +### 9.4 Smart Routing and Content Compliance Settings + +!!! note "" + In the **Smart Routing** tab, turn on the switch and select the simple model group and complex model group. The simple model group is suitable for low-cost tasks, while the complex model group is suitable for tasks such as code analysis, architecture design, and troubleshooting. + +![AI Gateway Smart Routing Settings](../../img/ai/ai_gateway_settings_smart_routing.png) +{: .browser-mockup} + +> In the **Content Compliance** tab, content compliance checks can be enabled or disabled uniformly. + +![alt text](../../img/ai/ai_gateway_settings_smart_routing_setCompliance.png) +{: .browser-mockup} +### 9.5 Log Settings + +!!! info "Parameter Description" + - **AI Gateway Log Retention Days**: Controls the retention period of the local gateway logs + - **Log Cleanup Interval**: Controls the execution interval of the background log cleanup task + - **Clear Logs**: Immediately clears the existing AI Gateway logs; use with caution + + +![alt text](../../img/ai/ai_gateway_settings_logsetting.png) +{: .browser-mockup} + +### 9.6 Elasticsearch Settings + +!!! note "" + Elasticsearch is used to save the request and response content of the AI Gateway, facilitating retrieval, audit, and troubleshooting. The page supports a connection test; confirm that the connection is available before saving the configuration. + +![AI Gateway Elasticsearch Settings](../../img/ai/ai_gateway_settings_elasticsearch.png) +{: .browser-mockup} + +!!! info "Parameter Description" + - **Enable**: Controls whether request and response content is written to Elasticsearch + - **Address**: The Elasticsearch service address, e.g., `http://127.0.0.1:9200` + - **Authentication Method**: Select the authentication method used by Elasticsearch + - **Username / Password**: Required when using Basic Auth + - **Index Prefix**: The index prefix used when writing data + - **Maximum Saved Size per Request Body**: Limits the request body size written in a single write; content exceeding the limit will be truncated + +> Request and response content may contain prompts, user input, or business context. Please restrict the network access scope, account permissions, and data retention period of Elasticsearch according to compliance requirements. diff --git a/docs/user_manual/ai/model.md b/docs/user_manual/ai/model.md index 0fde364af..4251ecca4 100644 --- a/docs/user_manual/ai/model.md +++ b/docs/user_manual/ai/model.md @@ -56,12 +56,12 @@ - [OpenWebUI](https://github.com/open-webui/open-webui) -### 0 Prerequisites +### 1 Prerequisites !!! note "" Before creating a model with TensorRT LLM, you must first install the NVIDIA GPU driver and configure the NVIDIA Container Toolkit. Refer to the documentation: [Installing the NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). -### 1 Create Model +### 2 Create Model !!! note "" On the TensorRT LLM Model Management page, click the **Create** button, enter parameters such as the model name, then click **Confirm** to create the model. @@ -82,12 +82,12 @@ ![img.png](../../img/ai/create_trtllm.png) {: .browser-mockup} -### 2 View Model Logs +### 3 View Model Logs !!! note "" On the TensorRT LLM Model Management page, click the **View Logs** button in the row of the target model to check the model startup and runtime logs. -### 3 Other Model Operations +### 4 Other Model Operations !!! note "" On the TensorRT LLM Model Management page, you can perform operations such as stop, start, restart, delete, and edit on the model. diff --git a/docs/user_manual/ai/skills_hub.md b/docs/user_manual/ai/skills_hub.md new file mode 100644 index 000000000..b795bf0b8 --- /dev/null +++ b/docs/user_manual/ai/skills_hub.md @@ -0,0 +1,82 @@ +--- +title: 1Panel Skills Hub User Guide +description: Introduces the Skill import, review and publishing, version management, custom agents, and offline usage of 1Panel Enterprise Edition Skills Hub. +keywords: 1Panel Skills Hub,AI Skill,Skill Management,Skill Review,Skill Publishing,Enterprise Edition +schema_type: TechArticle +--- + +# Skills Hub + +!!! info "Applicable Version and Permissions" + Skills Hub is only available in the 1Panel Enterprise Edition and requires a valid Enterprise Edition license. Viewing and managing are respectively controlled by the `Skills Hub` role permissions. + +!!! note "" + Skills Hub is used to import, review, publish, install, and maintain agent Skills within the enterprise, and retains version and risk check information. The entry point is **AI -> Skills Hub**. + +## 1 Importing a Skill + +The page supports the following sources: + +!!! note "" + - Upload a Skill archive in `.zip`, `.7z`, `.tar`, or `.tar.gz` format; the file must not exceed 5 MB and the archive must contain `SKILL.md`; + +![Upload Skill](../../img/ai/skills_hub_upload.png) +{: .browser-mockup} + +!!! note "" + - Import from a GitHub repository address and branch, or a Tag; + +![Import from GitHub Repository](../../img/ai/skills_hub_import_github.png) +{: .browser-mockup} + + +!!! note "" + - Import from a downloadable `.zip` package URL. + + +![Import from GitHub Repository](../../img/ai/skills_hub_import_detail.png) +{: .browser-mockup} + +!!! note "" + Fill in the version when importing. After the system completes parsing, it will record the Skill name, description, source, applicable agent, version, status, and risk level. + +## 2 Review and Publishing + +!!! note "" + Skill states include Pending Review, Reviewed, Published, Unpublished, Review Rejected, and Deleted. Users with management permissions can perform the operations of approve, reject, publish, unpublish, and delete. + + +!!! warning "Risk Check" + The risk check displays the risk level, file path, rule type, matched keyword, and description. Before publishing, the Skill content and its dependencies should be manually reviewed; the security should not be judged solely based on the automatic check results. + +![Skill List](../../img/ai/skills_hub_list_pending.png) +{: .browser-mockup} + +## 3 Version Management + +!!! note "" + In the Skill details, you can view the overview and version history. The version list records the status, risk level, creation time, publishing time, and version tag, and supports downloading published packages. + +## 4 Custom Agents + +!!! note "" + In **Custom Agents**, click **Add Agent** to configure the installation location of the Skill: + + - **Name**: Used to identify the target; + - **Node**: The 1Panel node where the Skill is installed; + - **Skill Directory**: The target directory where the package is extracted on the host; + - **Post-install Command**: The optional command executed after extraction is completed; + - **Description and Status**: Explain the purpose and control whether the target is selectable. +![alt text](../../img/ai/skills_hub_targets_button.png) +{: .browser-mockup} + +![Custom Agent List](../../img/ai/skills_hub_targets.png) +{: .browser-mockup} + +!!! note "" + When installing a Skill, you can select one or more enabled targets. The post-install command will be executed on the target node. Before configuring it, you should confirm the source of the command and the impact of its execution. + +## 5 Offline Environment + +!!! note "" + When the Enterprise Edition offline environment cannot directly access external GitHub repositories or package addresses, you should first prepare and review the Skill package in a networked environment, and then import it using the upload method. diff --git a/docs/user_manual/ai/vllm.md b/docs/user_manual/ai/vllm.md new file mode 100644 index 000000000..d169bf778 --- /dev/null +++ b/docs/user_manual/ai/vllm.md @@ -0,0 +1,66 @@ +--- +title: 1Panel vLLM Service Deployment and Management +description: Introduces the prerequisites, deployment parameters, and daily operations for creating, configuring, and managing vLLM inference services in 1Panel. +keywords: 1Panel vLLM,vLLM Deployment,LLM Inference,GPU Inference Service,OpenAI-Compatible Endpoint +schema_type: TechArticle +--- + +!!! note "" + vLLM is a high-throughput, memory-efficient inference and serving engine for large language models. 1Panel provides visual management capabilities on the **AI -> Model -> Local Models -> vLLM** page, which can be used to uniformly create, edit, start/stop, and maintain local vLLM services. + + This feature requires a **1Panel Professional Edition or Enterprise Edition** license. + +## 1 Prerequisites + +!!! note "" + Before creating a vLLM service, please confirm that the following conditions are met: + + - The server has installed the drivers and container runtime environment matching the selected vLLM image and accelerator device + - When using an NVIDIA GPU, `nvidia-smi` can normally display the graphics card information, and `NVIDIA Container Toolkit` has been configured + - When using Intel or Ascend accelerator devices, the driver and container runtime environment have been configured according to the corresponding vendor requirements + - The model files to be loaded have been placed in the local directory of the server in advance + + If you need to first check whether the GPU is available, refer to the [GPU Monitoring](./gpu.md) documentation. + +## 2 Creating a vLLM Service + +!!! note "" + After opening the 1Panel dashboard, enter **AI -> Model**, switch to **Local Models -> vLLM**, and click **Create**. + + Fill in the vLLM deployment parameters as required by the page, then click **Confirm** to start creation. The creation process will be executed in the background as a task, and after completion the service status can be viewed in the list. + +![img.png](../../img/ai/vllm_create.png) +{: .browser-mockup} + +!!! info "Parameter Description" + - **Name**: The name of the vLLM service, used for list display and subsequent management + - **Accelerator Device**: Select the NVIDIA, Intel, or Ascend type provided on the page according to the current server hardware. The available options depend on the current version and node detection results + - **Version**: Select the vLLM application version to be deployed. Different accelerator devices use different images and versions + - **Port**: The port through which the vLLM service provides its API to the outside, with `8000` available by default + - **Model Directory**: The local model directory on the server. After selection, 1Panel will mount this directory into the container + - **Startup Command**: The command parameters used to start the vLLM service. After selecting the model directory, the system will automatically generate a default command based on the directory name; if there are special inference parameter requirements, you can also adjust it yourself + +> After the vLLM service is created, it will provide inference capability to the outside in the form of an OpenAI-compatible endpoint, facilitating subsequent integration with agents or other AI applications. + +After creation is completed, the service can be synchronized as a **model account** for use by agents and other AI features. When synchronizing, you should confirm that the Base URL, API type, and model information are consistent with the actual service. + +## 3 Advanced Settings + +!!! note "" + If you need to further control the container runtime, you can expand **Advanced Settings**. + +!!! info "Advanced Settings Description" + - **Container Name**: Customizes the vLLM container name; by default it is automatically filled in following the service name + - **External Port Access**: After enabling, the firewall port will be opened to allow access to this service from the external network + - **Bind Host IP**: Used to restrict the port to bind only to a specified host address or network interface; if the purpose is unclear, it is recommended to keep the default + - **Restart Policy**: Configures the restart method after the container exits abnormally + - **CPU / Memory Limit**: Limits the host resources available to the vLLM container + - **Pull Image**: Actively pulls the image before startup to ensure that the image of the target version is used + - **Edit Compose File**: Allows manually adjusting the Compose configuration used for deployment; this option is suitable for experienced users, and improper modification may cause creation to fail + +## 4 Daily Management +!!! note "" + The list supports viewing the status and runtime directory, and provides operations such as edit, start, stop, restart, delete, view logs, and task tracking. Modifying the image, startup command, mounts, or resource limits may trigger container recreation; data that is not mounted to a host directory will not be retained with the container. + +!!! warning "External Access" + Before enabling external port access, you should restrict the access scope in combination with the firewall, authorized IPs, or a reverse proxy. The model API by default does not mean that identity authentication has been completed, and it should not be directly exposed to an untrusted network. diff --git a/docs/user_manual/appstore/deepseek-harness.md b/docs/user_manual/appstore/deepseek-harness.md new file mode 100644 index 000000000..ac2565708 --- /dev/null +++ b/docs/user_manual/appstore/deepseek-harness.md @@ -0,0 +1,103 @@ +# DeepSeek Harness Installation and Deployment + +## Product Introduction + +!!! note "" + **DeepSeek Harness (DSH for short)** is an open-source agent runtime environment launched by DeepSeek for developers. It provides project files, tools, and a runtime environment to large language models, enabling the models to complete development tasks. + + DeepSeek Harness adopts a plugin-based architecture, which can combine capabilities such as web search, Skills, planning, sub-agents, and workflows according to the task, and provides the following four runtime modes: + + - **Standard Mode**: Suitable for daily development tasks; it is recommended for first-time use + - **PTC Mode**: Suitable for multi-step, complex tool call orchestration + - **Minimal Mode**: Only retains the basic command and editing tools + - **Creation Mode**: Used to create and debug custom agent presets + + For more product information, please refer to the [DeepSeek Harness Official Documentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md). + +## Prerequisites + +!!! note "" + Before deployment, please confirm the following conditions: + + - 1Panel has been installed and can be accessed normally + - An API Key from DeepSeek or another model provider has been prepared + - The planned HTTPS port has been opened in both the cloud security group and the system firewall + - The IPv4 address or hostname used by your browser to actually access the server has been prepared + +## 1. Installing DeepSeek Harness + +!!! note "" + Log in to the 1Panel console, enter the **App Store**, search for **DeepSeek Harness**, enter the app details page, and click **Install**. + + Fill in the installation parameters as required by the page: + + - **Name**: The app name, which can be filled in as `deepseek-harness` by default + - **Version**: Select the DeepSeek Harness version to install + - **HTTPS Port**: Used to access the Web UI, e.g., `10443` + - **Access Address**: Fill in the IPv4 address or hostname actually used by your browser, without `https://` or the port + - **Web Username**: The authentication username used to access the Web UI + - **Web Access Password**: Set a strong password of at least 12 characters + - **Advanced Settings**: Generally keep the defaults +![Install DeepSeek Harness](../../img/app/deepseek-harness-search.png) +{: .browser-mockup} + +![Install DeepSeek Harness](../../img/app/deepseek-harness-install.png) +{: .browser-mockup} + +!!! note "" + The DeepSeek Harness in the 1Panel App Store integrates Caddy HTTPS and username/password authentication. Harness only listens on the container loopback address; external requests must first pass through Caddy's authentication and decryption before being forwarded to the Harness service. + +## 2. Accessing DeepSeek Harness + +!!! note "" + After the installation is completed, access the following address in your browser: + + ```text + https://: + ``` + + The browser will first ask for the Web username and password set during installation. After authentication succeeds, you can enter DeepSeek Harness. + +!!! warning "" + Caddy uses an internal CA to automatically issue the certificate, so the browser may prompt that the certificate is not trusted on the first visit. For a test experience, you can continue after confirming the address is correct; for a production environment, it is recommended to configure a certificate trusted by the browser. + +## 3. Configuring the DeepSeek Official Model + +!!! note "" + When entering DeepSeek Harness for the first time, the page will prompt you to add an API Key. Fill in the official DeepSeek API Key, then click **Save and Continue**. + + You can also click **Configure Later**, and after entering the page, open the **Settings** in the lower left corner and complete the configuration on the **Model** page. + + +## 4. Configuring a Third-Party Model Provider + +!!! note "" + DeepSeek Harness also supports configuring third-party model providers. Taking OpenCode Go as an example: + + 1. Open the **Settings** in the lower left corner. + 2. Enter the **Model** page and select **Add Provider**. + 3. Select `opencode-go` and fill in the API Key. + 4. Configure the API address and model as needed, and click **Save** after confirming they are correct. + +![Configure DeepSeek API Key](../../img/app/deepseek-harness-api-key.png) +{: .browser-mockup} + +## 5. Starting the First Task + +!!! note "" + Return to the home page, select the workspace in the lower left corner of the input box, confirm the model and runtime mode in the lower right corner, and then enter the task content to start the conversation. + + For the first experience, it is recommended to select **Standard Mode** and use a test project that does not contain sensitive data. + +![Start a DeepSeek Harness Task](../../img/app/deepseek-harness-task.png) +{: .browser-mockup} + +## 6. Security and Upgrade Recommendations + +!!! warning "" + DeepSeek Harness is still in the developer preview stage, so it is recommended for testing and experience only. Please pay attention to the following points: + + - Store the API Key and the Web access password properly + - Do not mount the host root directory, Docker Socket, or SSH key directory to the workspace + - Do not place sensitive data in the workspace + - Back up important data before upgrading diff --git a/docs/user_manual/appstore/hermes-agent.md b/docs/user_manual/appstore/hermes-agent.md new file mode 100644 index 000000000..0c910f1c7 --- /dev/null +++ b/docs/user_manual/appstore/hermes-agent.md @@ -0,0 +1,82 @@ +# Hermes Agent Installation and Deployment + +## Product Introduction + +!!! note "" + **Hermes Agent** is a self-improving AI agent built by Nous Research. It features a built-in learning loop that can create and improve skills from usage experience, retain long-term memory, retrieve historical sessions, and continuously build an understanding of the user across multiple sessions. + + Hermes Agent is not tied to a local computer; it can run in environments such as VPSs and GPU clusters, and can interact with users through the command line, Web UI, or messaging platforms. The 1Panel installation package provides a browser Web UI for managing configurations and API Keys, and for viewing runtime status and session information. + + This document is based on the **AI -> Agents** feature of 1Panel and introduces how to complete the installation, deployment, and basic verification of Hermes Agent. + + **Scan the QR code to join the communication group** + + Scan the QR code to join the communication group + +## Prerequisites + +!!! note "" + Before deployment, please confirm the following conditions: + + - 1Panel has been installed and can be accessed normally + - A usable large language model API Key has been prepared, or a local model has been integrated in 1Panel + - The server can access the internet normally + +## 1. Adding a Model Account + +!!! note "" + After entering the 1Panel dashboard, open the **AI** menu and enter the **Model Account** page. + + Click **Add Model Account**, fill in the corresponding information according to the model provider actually used, and save. + + After saving successfully, you can confirm in the model account list whether the newly created account is displayed normally. + +## 2. Creating a Hermes Agent + +!!! note "" + After completing the creation of the model account, enter the **Agents** page under the **AI** menu and click **Create**. + + In the agent type, select **Hermes Agent**, and then fill in the deployment parameters as required by the page. + +![Hermes_Agent_install.png](../../img/app/Hermes_Agent_install.png) +{: .browser-mockup} + +!!! note "Parameter Description" + - **Agent Type**: Select `Hermes Agent` + - **Name**: Can be filled in as `hermes-agent` by default, or customized as needed + - **Application Version**: Select the Hermes Agent version to install + - **Access Port / WebUI Port**: Configure according to the page defaults or actual requirements + - **Model Provider**: Select the provider corresponding to the model account created earlier + - **Model Account / Model**: Select the specific model according to the actual scenario + - **Other Parameters**: Generally keep the defaults + +!!! note "" + After selecting the model provider, the system will automatically load the maintained model accounts. + + If multiple models have been configured, you can select a specific model on the creation page; if there are additional configuration items, fill them in as prompted by the page. + + After the parameters are filled in, it is recommended to review the name, version, port, and model configuration once more to confirm they are correct before submitting the installation. + +## 3. Starting the Installation and Confirming Completion + +!!! note "" + After confirming that the parameters are correct, click **Confirm** to start the installation. + + When the page shows that the installation is complete, it means that Hermes Agent has been successfully deployed. + + If you need to check the progress during the installation, you can watch the status changes on the page and wait for the task to complete. + +## 4. Accessing the Hermes Agent WebUI + +!!! note "" + After the installation is completed, return to the **Agents** list page, find Hermes Agent, and click **WebUI** to jump to visit it directly. + + If the page is still initializing on the first visit, wait a moment and then refresh to access it. + +![Hermes_Agent_index.png](../../img/app/Hermes_Agent_index.png) +{: .browser-mockup} + +## 5. Subsequent Configuration Notes + +!!! note "" + After completing the basic deployment, you can continue to adjust the model, access methods, or other runtime parameters of Hermes Agent in 1Panel according to your actual business scenarios. diff --git a/docs/user_manual/cronjobs.md b/docs/user_manual/cronjobs.md index d0fd5395d..18eb7456e 100644 --- a/docs/user_manual/cronjobs.md +++ b/docs/user_manual/cronjobs.md @@ -1,20 +1,21 @@ !!! note "" This module is mainly used to manage scheduled tasks, such as periodically running a shell script, periodic backups, periodic URL visits, etc. Manual execution is also supported. -Basic concepts: - -- **Task Type**: Supports Shell Script, App Backup, Website Backup, Database Backup, Directory/File Backup, Log Backup, URL Visit, Website Log Rotation, Cache Cleanup, System Snapshot, Server Time Sync. -- **Group**: Classify tasks into different groups for quick filtering. -- **Schedule**: Custom schedule uses the **minute hour day month weekday** format (e.g., `0 0 * * *`). See https://crontab.guru/ for reference. You can preview the latest 5 execution times after setting. -- **Retention**: Keep only the latest *n* successful backups/logs to avoid unlimited growth. -- **Backup Account**: Target storage for backup files, managed in **Panel Settings → Backup Accounts**. Multiple accounts are supported. -- **Default Download Account**: One designated backup account used for download and file‑size checks. The task fails if this account upload fails; failures of other accounts are ignored. -- **Compression Password**: Encrypt tar backups using openssl (disabled by default). -- **Exclude Rules**: Skip specific files/directories during backup. -- **Alert (✨ Pro Edition)**: Send notifications (SMS/email) if a task fails. -- **Ignore Errors**: Continue backing up other items when one fails (e.g., backing up all databases). -- **Timeout**: Maximum allowed execution time. -- **Retry**: Number of retries after failure. +!!! note "" + Basic concepts: + + - **Task Type**: Supports Shell Script, App Backup, Website Backup, Database Backup, Directory/File Backup, Log Backup, URL Visit, Website Log Rotation, Cache Cleanup, System Snapshot, Server Time Sync. + - **Group**: Classify tasks into different groups for quick filtering. + - **Schedule**: Custom schedule uses the **minute hour day month weekday** format (e.g., `0 0 * * *`). See https://crontab.guru/ for reference. You can preview the latest 5 execution times after setting. + - **Retention**: Keep only the latest *n* successful backups/logs to avoid unlimited growth. + - **Backup Account**: Target storage for backup files, managed in **Panel Settings → Backup Accounts**. Multiple accounts are supported. + - **Default Download Account**: One designated backup account used for download and file‑size checks. The task fails if this account upload fails; failures of other accounts are ignored. + - **Compression Password**: Encrypt tar backups using openssl (disabled by default). + - **Exclude Rules**: Skip specific files/directories during backup. + - **Alert (✨ Pro Edition)**: Send notifications (SMS/email) if a task fails. + - **Ignore Errors**: Continue backing up other items when one fails (e.g., backing up all databases). + - **Timeout**: Maximum allowed execution time. + - **Retry**: Number of retries after failure. ## 1 Task Types diff --git a/mkdocs.yml b/mkdocs.yml index a91a9c4aa..e6cff4135 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_author: "1Panel Team" repo_name: "1Panel" repo_url: "https://github.com/1Panel-dev/1Panel" edit_uri: https://github.com/1Panel-dev/docs/edit/en/v2/docs/ -copyright: Copyright © 2025 Lingxia (Hong Kong) Software Co., Limited, All Rights Reserved. +copyright: Copyright © 2026 Lingxia (Hong Kong) Software Co., Limited, All Rights Reserved. ## customization theme: @@ -68,6 +68,10 @@ nav: - AI: - Agent: user_manual/ai/agent.md - Model: user_manual/ai/model.md + - vLLM: user_manual/ai/vllm.md + - AI Gateway: user_manual/ai/gateway.md + - Benchmark: user_manual/ai/benchmark.md + - Skills Hub: user_manual/ai/skills_hub.md - MCP: user_manual/ai/mcp.md - GPU Monitor: user_manual/ai/gpu.md - Website: @@ -136,6 +140,8 @@ nav: - Panel Settings: user_manual/settings.md - Popular Self-Hosted Apps: - OpenClaw: user_manual/appstore/openclaw.md + - Deepseek Harness: user_manual/appstore/deepseek-harness.md + - Hermes Agent: user_manual/appstore/hermes-agent.md - Ollama: user_manual/appstore/ollama.md - WordPress: user_manual/appstore/wordpress.md - Bitwarden: user_manual/appstore/bitwarden.md