在 Gaianet 上运行你自己的去中心化 AI 节点：安装、初始化、启动与配置全指南-平芜编程栈

AI 应用
大模型
CLI
RAG

【免费下载链接】gaianet-node

Install, run and deploy your own decentralized AI agent service

项目地址：https://gitcode.com/GitHub_Trending/ga/gaianet-node

本篇指南以 README-ja.md 的日文版操作手册为核心骨架，系统讲解如何在自己的 Mac、Linux 或 Windows WSL 机器上，用一条命令安装 GaiaNet 节点软件栈，并通过gaianet init、gaianet start、gaianet stop、gaianet config四个子命令完成节点全生命周期管理。读完本文，你将掌握从零部署一个带 RAG 知识库的私有 AI 代理服务、将其发布到 GaiaNet 公网域名、以及通过配置文件热更新模型与向量库参数的完整实战方案。

一、快速开始：一条命令装好节点

GaiaNet 的目标是让任何人都能运行自己的去中心化 AI 代理服务。在 Mac、Linux 或 Windows WSL 上，安装默认节点软件栈只需要一行命令：

curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash

安装完成后按屏幕提示设置环境变量路径（命令行以source开头，例如source $HOME/.bashrc），随后即可使用gaianet命令。快速验证版本：

gaianet --version

接着依次执行三个命令完成"初始化 → 启动 → 停止"的完整闭环：

gaianet init # 下载模型文件与向量数据库文件，文件较大可能需要几分钟 gaianet start # 启动节点 gaianet stop # 停止节点

启动成功后，脚本会在控制台打印官方节点地址，例如：

... ... https://0xf63939431ee11267f4855a166e11cc44d24960c0.us.gaianet.network

在浏览器中打开该 URL，即可查看节点信息并与节点上的 AI 代理进行对话。

二、安装指南：install.sh 做了什么

除了快速开始中使用的latest/download链接，你也可以显式从main分支安装：

curl -sSfL 'https://raw.githubusercontent.com/GaiaNet-AI/gaianet-node/main/install.sh' | bash

典型的安装输出如下：

[+] Downloading default config file ... [+] Downloading nodeid.json ... [+] Installing WasmEdge with wasi-nn_ggml plugin ... Info: Detected Linux-x86_64 Info: WasmEdge Installation at /home/azureuser/.wasmedge Info: Fetching WasmEdge-0.13.5 ... [+] Installing Qdrant binary... * Download Qdrant binary * Initialize Qdrant directory [+] Downloading the rag-api-server.wasm ... [+] Downloading dashboard ...

从仓库根目录的 install.sh 源码看，安装过程依次完成以下工作：

安装gaianetCLI 工具到$gaianet_base_dir/bin（默认$HOME/gaianet/bin）；
下载默认config.json（默认使用 config.json，当前仓库默认配置为 Qwen3-4B 聊天模型 + Nomic-embed-text-v1.5 嵌入模型）；
安装 WasmEdge 运行时及其 wasi-nn_ggml 插件（GGML 后端，用于在 WebAssembly 中推理 GGUF 模型），安装后源码source $HOME/.wasmedge/env使wasmedge命令立即可用；
安装 Qdrant 二进制并初始化 Qdrant 数据目录，同时会关闭 Qdrant 遥测（把config.yaml中的telemetry_disabled改为true）；
下载 LlamaEdge API Server（llama-api-server.wasm）；
下载 Cardea Agentic Search MCP server（用于基于 Qdrant 的 RAG 检索服务）；
下载 gaia-nexus（节点网关/编排服务）及其mcp_config.toml；
下载 dashboard（Web UI，即对话聊天界面）；
下载registry.wasm（用于生成节点 ID 与同步配置的 Wasm 工具，源码位于 utils/registry/src/main.rs）；
生成节点 ID：通过wasmedge --dir .:. registry.wasm执行注册表工具，写入nodeid.json与 keystore 文件；
安装 gaia-frp（基于 frp 的内网穿透客户端），下载 frpc.toml 模板，并用config.json中的address（子域名）、domain（域名）、deviceId回填其中的subdomain、serverAddr、name、metadatas.deviceId字段。

安装脚本还支持大量可选参数，适用于进阶场景：

# 安装到替代目录 curl -sSfL 'https://raw.githubusercontent.com/GaiaNet-AI/gaianet-node/main/install.sh' | bash -s -- --base $HOME/gaianet.alt # 指定 config.json 的 URL curl -sSfL '.../install.sh' | bash -s -- --config <Url> # 重装 / 升级 / 备份迁移 curl -sSfL '.../install.sh' | bash -s -- --reinstall curl -sSfL '.../install.sh' | bash -s -- --upgrade curl -sSfL '.../install.sh' | bash -s -- --backup <File> # 备份 config.json、nodeid.json、frpc.toml、keystore curl -sSfL '.../install.sh' | bash -s -- --migrate <File> # 从备份迁移到新节点 # CUDA 环境安装指定的 GGML CUDA 插件（11/12） curl -sSfL '.../install.sh' | bash -s -- --ggmlcuda 12

其中--backup/--migrate组合尤其适合换机迁移：备份文件以 tar 打包config.json、nodeid.json、gaia-frp/frpc.toml与 keystore 文件，迁移时在install.sh内自动解包恢复，从而保持原有节点 ID 不变（install.sh 第 99-117 行、第 204-220 行）。

三、初始化节点：gaianet init 的完整流程

安装完成后，用init子命令按$HOME/gaianet/config.json中的配置初始化节点：

gaianet init

典型输出：

[+] Downloading Llama-2-7b-chat-hf-Q5_K_M.gguf ... #################################################################### 100.0% [+] Downloading all-MiniLM-L6-v2-ggml-model-f16.gguf ... #################################################################### 100.0% [+] Creating 'default' collection in the Qdrant instance ... * Start a Qdrant instance ... * Remove the existed 'default' Qdrant collection ... * Download Qdrant collection snapshot ... * Import the Qdrant collection snapshot ... * Recovery is done successfully

对照 CLI 脚本 gaianet 中init()函数的实现，gaianet init实际执行四个阶段：

校验config.json：check_config_options会逐项检查address、chat、prompt_template、chat_ctx_size、system_prompt、embedding、embedding_ctx_size、snapshot、embedding_collection_name、qdrant_limit、qdrant_score_threshold、domain、llamaedge_port、llamaedge_chat_port、llamaedge_embedding_port等字段是否存在，缺任一字段即报错退出；
下载 GGUF 模型：从chat与embedding字段指向的 URL 下载聊天模型与嵌入模型到$HOME/gaianet/，若目标文件已存在则直接复用缓存，不再重复下载；
恢复向量库：若snapshot字段非空，则临时启动 Qdrant（监听 6333 端口），删除旧 collection，下载并导入快照（支持.tar.gz压缩包或裸快照文件），导入成功后停止 Qdrant 并输出 "Recovery is done successfully"；
准备 dashboard 与公网域名：运行wasmedge --dir .:. registry.wasm将config.json同步到 dashboard，并依据address、domain、llamaedge_port重写gaia-frp/frpc.toml中的subdomain、name、localPort、serverAddr。

使用预置配置或自定义 config.json

# 使用预置配置（llama-3 8B 模型 + 伦敦旅行指南知识库） gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-8b-instruct_london/config.json # 查看预置配置列表（default、paris_guide、mua、gaia 等） gaianet init --help

除gaianet_docs这类预置配置外，--config也接受任意指向自定义config.json的 URL——节点会按你提供的配置初始化到期望的状态（模型、知识库、上下文大小等均以该文件为准）。

初始化安装在替代目录的节点：

gaianet init --base $HOME/gaianet.alt

config.json 字段速查

仓库根目录的默认 config.json 是理解全部字段的最佳样例：

{ "address": "", "description": "The default GaiaNet node config with a Llama-3.2-3B-Instruct model.", "domain": "gaia.domains", "llamaedge_chat_port": "9068", "llamaedge_embedding_port": "9069", "llamaedge_port": "8080", "chat": "https://huggingface.co/second-state/Qwen3-4B-GGUF/resolve/main/Qwen3-4B-Q5_K_M.gguf", "chat_name": "Qwen3-4B", "chat_ctx_size": "16384", "chat_batch_size": "128", "chat_ubatch_size": "128", "prompt_template": "qwen3-no-think", "reverse_prompt": "", "system_prompt": "You are a helpful AI assistant. Please answer questions as clearly and concisely as possible.", "embedding": "https://huggingface.co/gaianet/Nomic-embed-text-v1.5-Embedding-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf", "embedding_name": "Nomic-embed-text-v1.5", "embedding_ctx_size": "8192", "embedding_batch_size": "8192", "embedding_ubatch_size": "8192", "snapshot": "", "embedding_collection_name": "default", "qdrant_limit": "1", "qdrant_score_threshold": "0.5" }

关键字段含义：

字段	含义	默认值示例
`address`	节点 ID（子域名前缀），由`registry.wasm`生成	空（init 时填充）
`domain`	GaiaNet 公网域名后缀，最终地址为`https://<address>.<domain>`	`gaia.domains`
`llamaedge_port`	gaia-nexus 网关端口（对外 API 入口）	`8080`
`llamaedge_chat_port`	聊天推理服务端口	`9068`
`llamaedge_embedding_port`	嵌入服务端口	`9069`
`chat`/`chat_name`	聊天模型 GGUF 下载 URL 及其展示名	Qwen3-4B 的 GGUF
`chat_ctx_size`	聊天模型上下文窗口大小（token）	`16384`
`chat_batch_size`/`chat_ubatch_size`	聊天模型批大小与微批大小	`128`
`prompt_template`	聊天模型的提示词模板	`qwen3-no-think`
`system_prompt`	系统提示词	通用助手指令
`embedding`/`embedding_name`	嵌入模型 GGUF URL 及其展示名	Nomic-embed-text-v1.5
`embedding_ctx_size`	嵌入模型上下文大小	`8192`
`snapshot`	Qdrant 集合快照 URL（为空则跳过 RAG 知识库恢复）	空
`embedding_collection_name`	Qdrant 集合名	`default`
`qdrant_limit`	RAG 检索返回的最大结果数	`1`
`qdrant_score_threshold`	RAG 检索结果的最小得分阈值	`0.5`

四、启动与停止节点

启动节点

gaianet start

启动输出示例：

[+] Starting Qdrant instance ... Qdrant instance started with pid: 39762 [+] Starting LlamaEdge API Server ... Run the following command to start the LlamaEdge API Server: wasmedge --dir .:./dashboard --nn-preload default:GGML:AUTO:Llama-2-7b-chat-hf-Q5_K_M.gguf --nn-preload embedding:GGML:AUTO:all-MiniLM-L6-v2-ggml-model-f16.gguf rag-api-server.wasm --model-name Llama-2-7b-chat-hf-Q5_K_M,all-MiniLM-L6-v2-ggml-model-f16 --ctx-size 4096,384 --prompt-template llama-2-chat --qdrant-collection-name default --web-ui ./ --socket-addr 0.0.0.0:8080 --log-prompts --log-stat --rag-prompt "Use the following pieces of context to answer the user's question.\nIf you don't know the answer, just say that you don't know, don't try to make up an answer.\n----------------\n" LlamaEdge API Server started with pid: 39796

从 gaianet 脚本的start()函数看，启动流程分为 4 步：

校验config.json并同步到 dashboard（再次执行registry.wasm）；
启动下游服务：先启动聊天服务（start_chat_server，基于chat、chat_ctx_size、prompt_template等字段拼装wasmedge命令，并对/v1/chat/completions做健康检查，失败自动重试最多 3 次），再启动嵌入服务（start_embedding_server，对/v1/embeddings做健康检查）；若snapshot非空（RAG 模式），再启动 Qdrant 与 Cardea Agentic Search MCP server；
启动 gaia-frp：以nohup方式运行frpc -c $gaianet_base_dir/gaia-frp/frpc.toml，建立到 GaiaNet 公网域名的隧道；
启动 gaia-nexus：作为节点编排网关，以--port $llamaedge_port对外提供 OpenAI 兼容 API，并通过register_chat_server/register_embedding_server把聊天与嵌入服务注册进网关。全部完成后打印公网地址：

✅ COMPLETED! The GaiaNet node is started at: https://<subdomain>.<domain>

本地模式启动

若只想本地使用，不发布到 GaiaNet 公网域名，使用--local-only：

gaianet start --local-only

该模式下节点仅通过http://localhost:<llamaedge_port>访问，不会启动 gaia-frp，也不出现在任何 GaiaNet 公网 URL 上。此模式适合调试或私有场景。脚本还支持：

# 启动安装在替代目录的节点 gaianet start --base $HOME/gaianet.alt # 即使 snapshot 为空也强制以 RAG 模式启动（需自行保证 Qdrant 已初始化快照） gaianet start --force-rag # 指定等待 gaia-nexus 就绪的秒数（默认 30 秒） gaianet start --wait 60

停止节点

gaianet stop

输出：

[+] Stopping WasmEdge, Qdrant and frpc ...

脚本内部执行stop_force，通过pkill依次清理qdrant、gaia-nexus、cardea-agentic-search、wasmedge、frpc全部进程，并删除$gaianet_base_dir下的qdrant.pid、chat_server.pid、embedding_server.pid、llama_nexus.pid、cardea_agentic_search_mcp.pid、gaia-frp.pid等 PID 文件。停止替代目录下的节点：

gaianet stop --base $HOME/gaianet.alt

五、更新配置：gaianet config 子命令

gaianet config子命令可更新config.json中的关键字段。注意：配置更新后必须重新执行gaianet init才能生效。

例如更新聊天模型 URL：

gaianet config --chat-url "https://huggingface.co/second-state/Llama-2-13B-Chat-GGUF/resolve/main/Llama-2-13b-chat-hf-Q5_K_M.gguf"

更新聊天模型上下文大小：

gaianet config --chat-ctx-size 5120

gaianet config --help的完整选项如下（以下为仓库当前版本输出）：

$ gaianet config --help Usage: gaianet config [OPTIONS] Options: --chat-url <url> 更新聊天模型的 URL。 --chat-ctx-size <val> 更新聊天模型的上下文大小。 --embedding-url <url> 更新嵌入模型的 URL。 --embedding-ctx-size <val> 更新嵌入模型的上下文大小。 --prompt-template <val> 更新聊天模型的提示词模板。 --port <val> 更新 LlamaEdge API Server 的端口。 --system-prompt <val> 更新系统提示词。 --rag-prompt <val> 更新 RAG 提示词。 --rag-policy <val> 更新 RAG 策略 [可能的值: system-message, last-user-message]。 --reverse-prompt <val> 更新反向提示词。 --domain <val> 更新 GaiaNet 节点的域名。 --snapshot <url> 更新 Qdrant 快照。 --qdrant-limit <val> 更新返回结果的最大数量。 --qdrant-score-threshold <val> 更新结果的最小得分阈值。 --base <path> GaiaNet 节点的基目录。 --help 显示此帮助信息

从 gaianet 源码的config分支看，脚本解析上述参数后调用update_config用sed就地改写config.json中对应的键值对，并逐个打印"旧值 → 新值"便于核对；--snapshot传空值时会把该字段清空（用于关闭 RAG 模式）。相比手册中列出的选项，仓库当前 CLI 还额外支持--chat-batch-size、--chat-ubatch-size、--embedding-batch-size、--embedding-ubatch-size、--chat-port、--embedding-port、--context-window（见脚本show_config_help），可按需使用。

六、验证节点：仓库自带的 Hurl 测试

仓库 tests/ 目录提供了可直接运行的 Hurl 测试，用于验证节点启动后的 API 行为，可作为"初始化 + 启动"是否成功的自动化判据：

tests/chat.hurl：验证/v1/models返回Qwen3-4B或Nomic-embed-text-v1.5；向/v1/chat/completions提问"法国首都是哪"，断言模型名与回答中包含 "Paris"；并验证即使传入不存在的模型名Qwen3-4B-Instruct-invalid，服务仍能正常回答；
tests/embeddings.hurl：验证/v1/embeddings对多段文本批量生成嵌入向量，断言返回Nomic-embed-text-v1.5且数据条数大于 0；
tests/rag.hurl：结合知识库提问"巴黎在塞纳河畔的位置"，验证 RAG 检索链路端到端可用。

这些测试也印证了节点对外暴露的是 OpenAI 兼容 API（/v1/models、/v1/chat/completions、/v1/embeddings），意味着你可以用任何 OpenAI SDK 直接对接自己的节点。

七、总结与故障排查要点

完整的节点生命周期操作可以归纳为：

阶段	命令	关键产物
安装	`curl ... install.sh \\| bash`	`$HOME/gaianet/bin/gaianet`、WasmEdge、Qdrant、dashboard
初始化	`gaianet init`	模型 GGUF、Qdrant 快照恢复、`frpc.toml`回填
启动	`gaianet start`	chat/embedding 服务、Qdrant、frpc、gaia-nexus
验证	`gaianet info`	显示 Node ID 与 Device ID
停止	`gaianet stop`	清理全部进程与 PID 文件
改配	`gaianet config ...`后重跑`gaianet init`	更新后的`config.json`

常见问题的处理思路：

gaianet init报"Not found the ... field in config.json"：说明配置文件缺少必需字段，参考上文字段速查表补齐后再执行；
端口被占用：脚本检测到llamaedge_chat_port/llamaedge_embedding_port已被监听时直接退出并触发stop_force，可通过gaianet config --chat-port/--embedding-port/--port更换端口；
聊天或嵌入服务启动失败：start内置 3 次重试并对/v1/chat/completions、/v1/embeddings做健康检查，持续失败可查看$HOME/gaianet/log/chat-server.log与embedding-server.log；
修改配置后不生效：gaianet config只更新config.json，必须重新gaianet init使新配置（新模型、新快照、新上下文）落地。