ModAI-BR-Companions - 带AI的同伴（巴西葡萄牙语）

[center][size=6][b]ModAI-BR-Companions[/b][/size]
[size=4][b]瓦爾海姆 1.0 的 AI 同伴 NPC — 巴西葡萄牙語版[/b][/size]

[img]https://raw.githubusercontent.com/julianu37/ModAI-BR-Companions/main/docs/images/banner.png[/img]

[b]你用葡萄牙語輸入或說出指令 — 同伴能聽懂、回應並服從。他也會說話。[/b]

[youtube]40FnVEIbXyo[/youtube]

[line]

[size=5][b]功能介紹[/b][/size]

這是 [b]Maddhattr[/b] 的 [url=https://www.nexusmods.com/valheim/mods/4047]Offline Companions Reborn[/url]（[b]MIT[/b]）的 [b]PT-BR 分支[/b]，而後者又是 [b]ProfMags[/b] 的 [i]Offline Companions[/i] 的分支。同伴本身（工作、食物與耐力、技能、房屋與休息、傳送門與推車、移動與戰鬥 AI、徑向選單）來自上游，運作方式不變。我們的分支新增了：

[list]
[][b]完整的 PT-BR 翻譯[/b] — 386 個介面鍵與 186 句同伴台詞，已審校（玩家看不到任何英文文字）。[/]
[][b]聊天中的文字指令[/b] — 一個 [b]本地 LLM[/b] 理解自然語言句子，同伴執行與徑向選單相同的動作。[/]
[][b]語音指令[/b] — 按住 [b]V[/b]，說話後放開：語音在[b]遊戲內[/b]轉錄（本地 STT），進入與聊天相同的流程，具有相同的人格與記憶。[/]
[][b]他會說話[/b] — PT-BR 合成語音（Kokoro-82M），從他在世界中的位置發出（3D 音效），按句播放並帶快取。[/]
[][b]人格、記憶與自由對話[/b] — PT-BR 預設（維京人、法師、諷刺、嚮導）或自訂文字；每個同伴記住最近的交流。[/]
[][b]遊戲內 AI 面板[/b]（按鍵 [b]I[/b]）— 人格、語音（含 [b]試聽[/b] 按鈕）、音量、速度、記憶、對話與按鍵通話鍵，全部即時儲存到
[code].cfg[/code]。[/]
[][b]帶目標的指令[/b] — 攻擊指定的生物、裝備與放下他已攜帶的物品、拾取地上的物品。[/]
[][b]按指令查看他的物品欄[/b] — 「打開你的物品欄」會打開同伴視窗，讓你查看他攜帶的物品。[/]
[][b]分支調整[/b] — 更大的拾取半徑、預設關閉隨機閒聊、[b]V[/b] 鍵不再觸發遊戲的自動拾取。[/]
[/list]
[spoiler][b]目前可用的指令範例[/b]
[code]colete 10 madeiras pega 10 pedras minere ferro
colhe as frutinhas segue para de me seguir
vem cá ataca o greydwarf mata o javali
equipa o machado de bronze pega a picareta larga a pedra
joga fora 5 madeira recolhe os itens abre o teu inventário
fica na defensiva parte pra cima cuida da plantação
vai pescar conserta as construções vai cozinhar
funde o minério vai caçar define a casa aqui
bom dia como você está?[/code]數字是[b]以他的物品欄計算的目標[/b]：當背包裡已有 10 個木材時要求「收集 10 個」，他會回答已經夠了，不會外出收集。[/spoiler]

[line]

[size=5][b]實際效果[/b][/size]

[img]https://raw.githubusercontent.com/julianu37/ModAI-BR-Companions/main/docs/wiki/images/1-ordem-no-chat.jpg[/img]
[i]聊天中的指令 — 你寫「colete 10 madeiras」，同伴理解、回應並外出收集。[/i]

[img]https://raw.githubusercontent.com/julianu37/ModAI-BR-Companions/main/docs/wiki/images/2-painel-da-ia.jpg[/img]
[i]AI 面板（按鍵 I）— 自訂人格、pt-BR 語音、音量、記憶與按鍵通話鍵。[/i]

[img]https://raw.githubusercontent.com/julianu37/ModAI-BR-Companions/main/docs/wiki/images/3-painel-f8.jpg[/img]
[i]F8 面板中的 [IA] 區段 — 全部可在遊戲內設定，無需編輯檔案。[/i]

[img]https://raw.githubusercontent.com/julianu37/ModAI-BR-Companions/main/docs/wiki/images/4-menu-radial.jpg[/img]
[i]徑向選單（看著同伴按住 E）— 原有指令照常運作。[/i]

[line]

[size=5][b]⚠️ 需求[/b][/size]

[list]
[][b]瓦爾海姆 1.0.x[/b]（Unity 6 引擎 — 已在 1.0.17 測試）。[/]
[][b]BepInExPack_Valheim 5.4.2351[/b]（BepInEx 5.4.23.5）。[b]不需要 Jotunn[/b] — 本模組不使用該框架的任何 API（既無依賴宣告，也無建置參考）。[/]
[][b]Windows x64[/b] — 語音的兩個部分都必須：識別（whisper.cpp）與語音（sherpa-onnx + onnxruntime）的原生二進位檔皆為 win-x64。在非 Windows x64 環境下，語音指令與同伴說話無法運作（模組其餘功能正常）。[/]
[][b]LM Studio[/b]（或任何相容 OpenAI API 的伺服器）並載入模型 — 建議且已測試的是 [b]qwen2.5-3b-instruct[/b]，Q4_K_M 量化（約 1.93 GB）。[/]
[][b]麥克風[/b] — 僅用於語音指令。沒有麥克風時使用聊天：文字指令可獨立運作。[/]
[][b]磁碟空間[/b] — 模組與語音模型約需 1 GB，再加上 LLM 模型的空間。[/]
[/list]
[b]多人遊戲：[/b]所有玩家都必須安裝此模組。

[line]

[size=5][b]安裝[/b][/size]

完整的逐步說明[b]附圖片[/b]（包括 LM Studio 設定）在專案 wiki 中：
[url=https://github.com/julianu37/ModAI-BR-Companions/wiki/Instalacao]github.com/julianu37/ModAI-BR-Companions/wiki/Instalacao[/url]

摘要：

[list=1]
[]將 [b]BepInExPack_Valheim 5.4.2351[/b] 安裝到遊戲資料夾並執行瓦爾海姆一次（讓 BepInEx 建立資料夾）。[/]
[]將模組資料夾解壓縮到
[code]...\Valheim\BepInEx\plugins\ModAI-BR-Companions\[/code][/]
[]確認模型位於
[code]...\ModAI-BR-Companions\whisper\[/code]和
[code]...\ModAI-BR-Companions\tts\kokoro\[/code]— [b]完整[/b]套件已包含它們。[/]
[]在 LM Studio 中：載入模型，啟動 Local Server（連接埠 1234），並在
[code].cfg[/code]的
[code][IA][/code]區段確認：
[code]BaseUrl = http://127.0.0.1:1234/v1[/code]和
[code]Modelo = qwen2.5-3b-instruct[/code]。[/]
[]進入世界並在聊天中輸入
[code]colete 10 madeiras[/code]— 或按住 [b]V[/b] 說話。[/]
[/list]
日誌（
[code]BepInEx\LogOutput.log[/code]）中應出現
[code]ModAI-BR-Companions v… loading...[/code]和
[code]… loaded successfully! (N methods patched)[/code]這些行。啟動時的 PlayFab/NullReferenceException 錯誤是遊戲本身的，不是模組的。

下載與更新日誌：[url=https://github.com/julianu37/ModAI-BR-Companions/releases]github.com/julianu37/ModAI-BR-Companions/releases[/url]

[line]

[size=5][b]檔案[/b][/size]

頁面有[b]兩個檔案[/b]，它們的差別[b]僅在語音模型[/b]（模組與翻譯相同）：

[list]
[][b]ModAI_BR_Companions-1.6.3.zip[/b]（約 368 MB）— 模組[b]和[/b]已備妥的語音模型（識別與語音）。這是[b]推薦[/b]的檔案：解壓即玩。[/]
[][b]ModAI_BR_Companions-1.6.3-sem-modelos.zip[/b]（約 28 MB）— 僅模組與翻譯，適合網速慢或已有模型的人。它已附帶
[code]tokens.txt[/code]和
[code]espeak-ng-data\[/code]資料夾；只缺下面兩個模型。[/]
[/list]
如果你選擇[b]不含模型[/b]的版本，請放入：

[list]
[][code]...\ModAI-BR-Companions\whisper\ggml-small-q5_1.bin[/code]— 語音識別模型（181 MB）。
[code]ggml-base-q5_1.bin[/code]（57 MB）也可用且更快，但葡萄牙語錯誤較多。下載於 [url=https://huggingface.co/ggerganov/whisper.cpp/tree/main]huggingface.co/ggerganov/whisper.cpp[/url][/]
[][code]...\ModAI-BR-Companions\tts\kokoro\[/code]—
[code]model.int8.onnx[/code]（109 MB）、
[code]voices.bin[/code]（27 MB）、
[code]tokens.txt[/code]和
[code]espeak-ng-data\[/code]資料夾。來自 [b]kokoro-int8-multi-lang[/b] 模型套件，位於 [url=https://github.com/k2-fsa/sherpa-onnx]sherpa-onnx[/url] 的發佈頁。[/]
[/list]
[line]
[size=5][b]使用方法[/b][/size]

[b]按鍵[/b]

[list]
[][b]V[/b] — 按鍵通話：按住、說話、放開，讓他理解。[/]
[][b]Z[/b] — 指令鍵：看著某物並點按以命令同伴（移動、攻擊、開門、坐下、修理）。按住可召喚他們。[/]
[][b]E[/b] — 看著同伴按住以打開[b]徑向選單[/b]；點按以打開他的面板/物品欄。[/]
[][b]I[/b] — [b]AI 面板[/b]：人格、語音（含[b]試聽[/b]）、音量、速度、記憶、對話與按鍵通話鍵。[/]
[][b]F8[/b] — 模組設定面板（所有選項，遊戲內）。[/]
[][b]F5[/b] — 遊戲主控台，用於測試指令
[code]modia_tts_teste[/code]和
[code]modia_stt_teste[/code]。[/]
[][b]LeftAlt + Z[/b] — 農場區域編輯器。[/]
[/list]
[b]指令[/b] — 在遊戲聊天中輸入[b]或[/b]按住 [b]V[/b] 說話。兩種輸入進入同一個地方，所以文字可行的語音也可行（人格、記憶與對話相同）。你可以用多種方式表達同一件事：指令由 LLM 解讀，不是背誦的句子清單。

[line]
[size=5][b]重要注意事項（請閱讀）[/b][/size]

[list]
[][b]使用[/b]
[code]127.0.0.1[/code][b]，而非[/b]
[code]localhost[/code][b]。[/b]在 Windows 上，
[code]localhost[/code]會先解析為 IPv6，而 LM Studio 伺服器只監聽 IPv4：因此每個指令會多等約 [b]2.5 秒[/b]。[/]
[][b]指令中的數字是目標[/b]，以同伴的物品欄（他的背包 — 不計箱子或地上的堆疊）計算，且僅適用於所要求的資源。[/]
[][b]同伴的語音不經過遊戲混音器：[/b]它忽略瓦爾海姆的音量滑桿，服從
[code][IA] TtsVolume[/code]（或 [b]I[/b] 面板的滑桿）。[/]
[][b]第一個語音指令（以及第一句說出的話）可能較久：[/b]Whisper 模型在你第一次使用麥克風時載入。[/]
[][b]移除原版 Offline Companions（ProfMags）。[/b]它無法在瓦爾海姆 1.0 運作，且只要它安裝著，本模組就不會啟動。[/]
[][b]不要與 Offline Companions Reborn 一起安裝：[/b]兩者使用相同的插件 GUID 與相同的設定檔。[/]
[][b]設定檔保留上游名稱[/b] —
[code]BepInEx\config\Maddhattr.OfflineCompanionsReborn.cfg[/code]— 這是刻意的，讓已使用該模組的人的設定繼續有效。[/]
[][b]未啟動 LLM 時[/b]模組正常載入：同伴繼續執行原本的所有功能，但無法理解書寫或口說指令。[/]
[/list]
[line]

[size=5][b]運作原理（摘要）[/b][/size]

共有[b]三個 AI 元件，全部本地[/b]：

[list]
[][b]LLM[/b] — 理解指令並對話：LM Studio，或任何相容 OpenAI API 的伺服器。[/]
[][b]STT[/b] — 轉錄你的語音：Whisper.net（whisper.cpp）在遊戲內於 CPU 上執行。[/]
[][b]TTS[/b] — 讓同伴說話：sherpa-onnx 搭配 Kokoro-82M 模型，在遊戲內於 CPU 上執行。[/]
[/list]
對模型的請求帶有 [b]JSON schema[/b]（
[code]response_format[/code]），固定意圖的五個鍵與 29 個動作的封閉清單 — 這讓小模型也能正確輸出格式。在專案測量中，使用目前提示，[b]qwen2.5-3b-instruct[/b] 在開啟結構化輸出後從 0/6 提升到 [b]6/6[/b] 有效回應，並在約 0.35–0.4 秒內回應一個指令。若伺服器不支援該格式，模組會自行降級為鬆散 JSON，再降級為舊格式，並在日誌中提示。

這些都不會卡住遊戲：LLM 呼叫在背景 task 中執行，STT/TTS 在背景執行緒中執行，佇列在
[code]Update[/code]中排空。

[line]

[size=5][b]隱私與網路[/b][/size]

[list]
[]預設情況下，模組[b]只與本地 LLM 通訊[/b] —
[code][IA] BaseUrl[/code]預設為
[code]http://localhost:1234/v1[/code]（我們建議
[code]http://127.0.0.1:1234/v1[/code]）。不會聯絡我們的任何伺服器。[/]
[]你的語音在[b]遊戲內[/b]轉錄，同伴的語音在[b]遊戲內[/b]合成：沒有任何音訊離開你的機器。[/]
[]模組[b]沒有遙測[/b]，不向我們發送任何東西 — 無論你輸入或說出的內容。[/]
[]可以將
[code][IA] BaseUrl[/code]指向遠端服務（例如付費 API）並填寫
[code][IA] ApiKey[/code]。這樣你的訊息會離開你的電腦 — 這是你的選擇。金鑰僅存於本地
[code].cfg[/code]；請勿分享填有金鑰的該檔案。[/]
[/list]
[line]

[size=5][b]🤖 AI 揭露[/b][/size]

本模組[b]大量使用生成式 AI[/b]，並已在頁面標籤中聲明：[b]AI-Generated Content[/b] 與 [b]AI Media[/b]。

[b]本模組中的 AI 部分：[/b]

[list]
[][b]同伴的語音[/b]由開放模型（Kokoro-82M，Apache-2.0）在你的機器上即時 AI 合成。[b]沒有人類配音員[/b] — 也沒有任何人類聲音被複製、模仿或未經許可使用。[/]
[][b]自由對話的台詞[/b]由運行在你機器上的 LLM 生成，使用[b]你[/b]選擇的模型。模組的固定台詞（確認、警告、指令台詞）是人類撰寫的文字。[/]
[][b]PT-BR 翻譯[/b]（386 個介面鍵與 186 句同伴台詞）在生成式 AI 協助下製作，之後經審校與修訂。[/]
[][b]本分支的程式碼[/b] — AI 層（指令、STT/TTS、面板）與調整 — 在 AI 協助下撰寫。[/]
[][b]展示美術[/b] — 橫幅、套件圖示與影片縮圖 — 是 AI 生成的藝術。屬於展示素材，[b]不在遊戲內[/b]。[/]
[/list]
[b]非 AI 部分：[/b]

[list]
[]同伴本身 — 工作、食物與耐力、技能、房屋與休息、傳送門與推車、移動與戰鬥 AI、徑向選單及所有基礎 UI — 是上游程式碼（[b]Offline Companions Reborn[/b]，Maddhattr 著，以及 ProfMags 的原版），由人類撰寫並以 MIT 授權再散布。[/]
[]模組[b]不新增任何 AI 生成的遊戲資產[/b]：這裡面沒有 AI 建立的 3D 模型、材質、物品、音效或動畫。[/]
[]語音識別與語音合成使用第三方開放模型（Whisper/whisper.cpp、Kokoro-82M、sherpa-onnx、onnxruntime），連同其授權文本散布於套件的
[code]LICENSES\[/code]資料夾中。[/]
[]不會用你的資料訓練任何東西：你寫或說的內容留在你的機器上，不會用於訓練任何模型。[/]
[/list]
[quote][b]為什麼我們不使用「AI Assisted」標籤？[/b]因為它需要證明開發以人類為主，而我們無法誠實地證明這一點。本專案的 AI 使用是大量的，我們寧願公開聲明為 [b]AI-Generated Content[/b]（加上 [b]AI Media[/b] 標籤用於頁面美術）。[/quote]
[line]

[size=5][b]致謝[/b][/size]

[list]
[][b]Offline Companions Reborn[/b] — [b]Maddhattr[/b]（[url=https://www.nexusmods.com/valheim/mods/4047]Nexus 頁面[/url] · [url=https://github.com/MaddhattrRocks/Offline-Companions-Reborn]GitHub[/url]）— [b]MIT[/b]。同伴的來源：工作、移動與戰鬥 AI、UI、徑向選單及一切基礎。[/]
[][b]Offline Companions[/b]（原版）— [b]ProfMags[/b] — [b]MIT[/b]。概念與原始程式碼。[/]
[][b]Whisper.net[/b]（sandrohanea）與 [b]whisper.cpp[/b]（ggerganov）— [b]MIT[/b] — 語音識別。[/]
[][b]sherpa-onnx[/b]（k2-fsa）— [b]Apache-2.0[/b] — TTS 執行環境。[/]
[][b]Kokoro-82M[/b]（hexgrad）— [b]Apache-2.0[/b] — 語音模型。[/]
[][b]onnxruntime[/b]（Microsoft）— [b]MIT[/b] — ONNX 模型的執行環境。[/]
[][b]espeak-ng-data[/b] — [b]GPL-3.0[/b]，僅作為語音模型的音素化[b]資料[/b]使用（沒有任何 espeak-ng 程式碼連結到模組）。[/]
[][b]LM Studio[/b] 與 [b]Qwen2.5[/b] 模型（[url=https://lmstudio.ai]lmstudio.ai[/url] · [url=https://huggingface.co/Qwen]huggingface.co/Qwen[/url]）— 運行在你機器上的「大腦」（不在此處散布）。[/]
[/list]
第三方授權的完整文本隨[b]套件內[/b]的
[code]LICENSES\[/code]資料夾散布，與
[code]Companions.dll[/code]一起。

原始碼、wiki 與更新日誌：
[url=https://github.com/julianu37/ModAI-BR-Companions]github.com/julianu37/ModAI-BR-Companions[/url] · [url=https://github.com/julianu37/ModAI-BR-Companions/wiki]專案 wiki[/url]

[line]

[size=5][b]授權[/b][/size]

[b]MIT[/b] — 你可以使用、修改與再散布，並保留著作權聲明。

本模組是 Offline Companions Reborn（MIT，Maddhattr 著）與 Offline Companions（MIT，ProfMags 著）的[b]非官方分支[/b]。它是[b]獨立分支[/b]：上游的同伴[b]隨[/b]本套件一起散布（不是與其並行執行的附加元件）— 這就是它不應與原版或 Reborn 一起安裝的原因。MIT 授權明確允許在標註來源的情況下再散布與修改作品，兩位作者的著作權聲明與我們的變更一併保留，符合授權要求（見儲存庫中的
[code]LICENSE[/code]、
[code]NOTICE.md[/code]和
[code]THIRD_PARTY_NOTICES.md[/code]）。

與 Iron Gate Studio、Coffee Stain Publishing、ProfMags 或 Maddhattr 無關，也未獲其背書。「Valheim」及其他商標屬於其各自所有者。若任何作者希望修改、移除或納入某些內容，只需提出即可。[/center]