Mwongozo wa Msaidizi wa Ndani wa Kusoma na Kuhariri Makala: Kusambaza CLI Agent Inayolinda Faragha kwenye Linux

Utangulizi wa mradi

Msaidizi wa ndani wa kusoma na kuhariri makala ni CLI Agent mwepesi wa kusaidia makala, unaolenga Linux. Mtumiaji anapoingiza swali, modeli inaweza kutumia zana za ndani na uwezo wa kutafuta makala ili kusaidia kusoma, kufupisha na kuchanganua maudhui ya makala za ndani.

Kwa chaguo-msingi, mradi hutumia Qwen3-14B-AWQ, ambao uzito wa modeli ni takriban 9.4 GB. Unafaa kwa watumiaji walio na NVIDIA GPU wanaotaka kuendesha modeli ndani ya kifaa na kulinda faragha ya makala na maswali yao. Kwa chaguo-msingi, mradi hauwashi utafutaji wa mtandaoni; majibu hutokana hasa na uwezo wa modeli yenyewe pamoja na hifadhidata ya maarifa ya ndani iliyoundwa na mtumiaji.

Mradi unaunga mkono itifaki ya MCP na unaweza kuunganisha huduma za MCP kupitia utaratibu wa kusajili zana. Kwa kuwa bajeti ya ingizo, maelekezo ya mfumo na urefu wa matokeo ya zana vinaweza kusanidiwa, matumizi yake hayaishii kwenye usaidizi wa makala pekee.

Sifa kuu

• Kuendesha Agent wa ndani wa kusaidia makala katika mazingira ya Linux.
• Kutumia modeli ya ndani Qwen3-14B-AWQ kwa chaguo-msingi.
• Kuunda hifadhidata ya maarifa ya utafutaji kutoka kwa PDF zenye maandishi, Markdown na TXT.
• Kuunga mkono maswali shirikishi na utekelezaji wa swali moja kupitia mstari wa amri.
• Kuhifadhi rekodi za maswali na majibu katika muundo wa Markdown.
• Kuunga mkono itifaki ya MCP na utaratibu wa kusajili zana.
• Kuunga mkono vituo vya ukaguzi vya hiari vya LangGraph kwa kuendelea na kikao kwenye dirisha jingine.
• Kutoa hati za kukagua mazingira, GPU na usanidi wa modeli.

Maandalizi kabla ya usakinishaji

Mradi unalenga Linux na unapendekeza kutumia mashine yenye NVIDIA GPU. Uzito wa modeli ni takriban 9.4 GB, na wakati wa uendeshaji lazima kuwe na VRAM ya kutosha kwa uelekezaji wa modeli. Unaporekebisha modeli, bajeti ya ingizo au urefu wa matokeo, tathmini kulingana na ukubwa wa VRAM.

PDF zilizochanganuliwa haziungi mkono OCR kwa sasa. Ikiwa unahitaji kutafuta katika makala zilizochanganuliwa, badilisha maudhui kuwa maandishi kwanza, au tumia PDF zenye maandishi, Markdown na TXT zinazoungwa mkono na mradi.

Pakua na sakinisha mradi

Kwanza kloni hazina ya GitHub na uitaje saraka ya mradi local-agent:

git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agent

Usipotumia Git, unaweza pia kuchagua Code → Download ZIP kwenye ukurasa wa GitHub, kufungua faili hiyo, kisha ufungue terminali katika saraka ya mradi.

Baada ya kuingia kwenye saraka ya mradi, endesha hati ya usakinishaji:

bash scripts/install.sh

Usakinishaji ukikamilika, endesha hati ya kuanzisha:

bash scripts/start.sh

Wakati wa kuanza mara ya kwanza, subiri modeli ipakie. Alama ya >>> inapoonekana kwenye terminali, unaweza kuingiza swali. Kwa mfano:

>>> Eleza tatizo linalotatuliwa na miunganisho ya mabaki

Baada ya hapo, ukiingia kwenye saraka ya mradi, kwa kawaida utaendesha tu bash scripts/start.sh ili kuanza.

Uendeshaji wa kwanza na usanidi wa modeli

Ikiwa saraka ya modeli haijakamilika au unahitaji kuchagua modeli upya, unaweza kutekeleza:

bash scripts/setup.sh

Upakuaji wa modeli ukishindikana, kagua mtandao kwanza. Unaweza pia kupakua saraka kamili ya modeli kwenye mashine yenye mtandao, kuinakili kwenye mashine lengwa, kisha uchague modeli iliyopo wakati wa usanidi.

Modeli ikishindwa kuanza, angalia faili ya kumbukumbu iliyoonyeshwa kwenye terminali. Kwa kawaida kumbukumbu hupatikana hapa:

logs/cli-vllm-*.log

Pia hakikisha kuwa VRAM ya GPU haitumiwi na programu nyingine.

Ingiza makala zako na uunde faharasa

Ili Agent ajibu kulingana na makala zako, weka PDF zenye maandishi, faili za Markdown au TXT kwenye saraka ya data/knowledge/. Kwa mfano, saraka inaweza kuwa na makala kadhaa na madokezo yanayohusiana.

Faili zikiwa tayari, tekeleza amri ya kuorodhesha hifadhidata ya maarifa:

bash scripts/start.sh rag-index

Wakati wa kuunda faharasa kwa mara ya kwanza, modeli tofauti ya utafutaji itapakuliwa, hivyo muunganisho wa mtandao unahitajika. Baada ya faharasa kukamilika, anzisha tena Agent shirikishi:

bash scripts/start.sh

Sasa unaweza kuuliza maswali yanayotegemea makala za ndani, kwa mfano:

Fupisha ubunifu mkuu wa YOLOv1 kulingana na makala za ndani, na taja vyanzo.

Usipoweka makala au usipounda faharasa, majibu yatatokana hasa na maarifa ya modeli yenyewe, si maudhui ya makala za ndani. Mradi hauwashi utafutaji wa mtandaoni kwa chaguo-msingi.

Matumizi shirikishi

Baada ya kuanza, ingiza swali baada ya alama ya >>> na ubonyeze Enter. Hii inafaa kwa maswali ya kufuatilia, kulinganisha mitazamo ya makala au kuchanganua mada moja hatua kwa hatua.

Unaweza kutumia amri zifuatazo zilizojengwa ndani kudhibiti mchakato wa mazungumzo:

• /help: Tazama amri za mazungumzo.
• /new: Anza kikao kipya.
• /exit, /quit au Ctrl+D: Toka kwenye programu.

Kila swali na jibu huhifadhiwa kwa chaguo-msingi kama faili ya Markdown, yenye muundo wa njia:

output/mwezi/siku/muda_microseconds.md

Tekeleza kazi ya mara moja kupitia mstari wa amri

Usipohitaji kuingia kwenye kiolesura shirikishi, unaweza kupitisha swali moja kwa moja kama kigezo cha hati ya kuanzisha:

bash scripts/start.sh "Fupisha utaratibu wa umakini"

Tumia --quiet ili kutoa jibu pekee:

bash scripts/start.sh "Fupisha utaratibu wa umakini" --quiet

Usipotaka kuhifadhi faili ya jibu, ongeza --no-save:

bash scripts/start.sh "Swali" --no-save

Sanidi bajeti ya ingizo, urefu wa matokeo na maelekezo

Bajeti ya ingizo ya Agent na maelekezo ya mfumo yanaweza kubadilishwa katika config/agent.yaml, hivyo mradi unaweza kutumika pia katika hali nyingine za Agent wa ndani.

Ni muhimu kutofautisha vigezo viwili: tool_output_max_chars: 4000 katika faili ya usanidi ni kikomo cha kukata herufi za matokeo ya zana, si kikomo cha tokeni za jibu la modeli. Urefu wa juu wa matokeo ya modeli hudhibitiwa na LOCAL_AGENT_MAX_TOKENS katika faili ya mazingira; .env.example huweka kwa chaguo-msingi tokeni 2048.

Bajeti ya ingizo ya Agent ni tokeni 4096 kwa chaguo-msingi. Unaporekebisha bajeti ya ingizo, maelekezo ya mfumo, urefu wa matokeo ya zana au tokeni za juu za matokeo, zingatia kwa pamoja urefu wa muktadha na VRAM inayopatikana ili kuepuka usanidi wa juu sana unaoweza kuzuia modeli kufanya kazi ipasavyo.

Hifadhi na rejesha kikao kwenye madirisha tofauti

Kwa chaguo-msingi, muktadha wa kikao huhifadhiwa tu katika mchakato wa sasa. Ukifunga CLI, programu haitarejesha muktadha kiotomatiki, wala haitasoma tena faili za majibu za Markdown zilizoundwa.

Ikiwa unahitaji kuendelea na kikao hicho hicho kwenye dirisha jingine, badilisha run.checkpoint_enabled kuwa true katika config/agent.yaml, na utumie kila mara kitambulisho hicho hicho cha kikao:

bash scripts/start.sh -i --thread-id my-paper

Hali ya kikao itahifadhiwa kwenye:

data/checkpoints/langgraph.sqlite

Ukiingiza /new, au ukianzisha dirisha jipya la maingiliano bila kutaja kitambulisho cha kikao, kikao kipya kitaundwa. Kila mwito wa modeli hutumia mazungumzo 4 ya hivi karibuni kwa chaguo-msingi, na bado unazuiwa na bajeti ya ingizo ya tokeni 4096.

Ukaguzi wa mazingira na utatuzi wa matatizo

Unapokumbana na tatizo, inashauriwa kuendesha kwanza hati ya ukaguzi wa mazingira:

bash scripts/doctor.sh

Hati hii hukagua mazingira, GPU na usanidi wa modeli, lakini haipakii modeli kubwa wala kuanza uelekezaji. Kwa hiyo inafaa kuitumia kabla ya kuanza rasmi au wakati wa kutatua matatizo.

• Hakuna GPU: Inashauriwa kutumia mashine ya Linux yenye NVIDIA GPU.
• Saraka ya modeli haijakamilika: Endesha bash scripts/setup.sh, chagua modeli upya au endelea na upakuaji.
• Upakuaji wa modeli umeshindikana: Kagua mtandao, au pakua saraka kamili ya modeli kwenye mashine yenye mtandao kisha uinakili kwenye mazingira lengwa.
• Modeli imeshindwa kuanza: Angalia logs/cli-vllm-*.log na uhakikishe kuwa VRAM haitumiwi na programu nyingine.
• Makala za ndani hazitumiki: Hakikisha faili ziko kwenye data/knowledge/ na kwamba tayari umetekeleza bash scripts/start.sh rag-index.

Mapendekezo ya matumizi

• Kabla ya kutumia kwa mara ya kwanza, endesha bash scripts/doctor.sh ili kugundua mapema matatizo ya GPU, saraka ya modeli au usanidi.
• Weka makala unazohitaji kunukuu na kuchanganua pamoja kwenye data/knowledge/, kisha uliza maswali baada ya kukamilisha faharasa.
• Unapouliza, bainisha upeo wa muhtasari, muundo wa matokeo au omba vyanzo ili kurahisisha uhakiki wa maudhui ya makala za ndani.
• VRAM ikiwa haitoshi, usiongeze bila kufikiria bajeti ya ingizo, kikomo cha matokeo ya zana au tokeni za juu za matokeo.
• Unaposhughulikia mada hiyo hiyo ya utafiti kwa mfululizo, washa vituo vya ukaguzi na uweke --thread-id isiyobadilika.
• PDF zilizochanganuliwa haziwezi kutegemewa moja kwa moja kwa OCR katika mradi huu; andaa kwanza maudhui ya maandishi yanayotafutika.

Muhtasari

paperchecker hutoa mtiririko kamili kutoka kuanzisha modeli ya ndani, kuorodhesha makala hadi kuuliza maswali kupitia CLI. Baada ya kusakinisha mradi, unaweza kutumia modeli ya chaguo-msingi kuchanganua maswali ya jumla, au kuweka makala zako zenye maandishi kwenye hifadhidata ya maarifa na kuunda faharasa ili Agent ajibu kulingana na nyenzo za ndani. Kupitia agent.yaml, vigezo vya mazingira na vituo vya ukaguzi vya vikao, unaweza pia kurekebisha zaidi muktadha, matokeo na usimamizi wa vikao.

Msimbo wa mradi unatumia Leseni ya MIT. Ukikumbana na matatizo ya kuanza au ya modeli, endesha kwanza hati ya uchunguzi na ukague kumbukumbu.