Kuunda Msaidizi wa Huduma kwa Wateja wa Biashara ya Mtandaoni kwa Adaptive-RAG: Utafutaji Unaobadilika, Utambuzi wa Nia na Zana za Oda

Muhtasari wa Mradi

Adaptive-RAG Huduma kwa Wateja ya Biashara ya Mtandaoni ni mradi wa huduma mahiri kwa wateja unaolenga mashauriano ya sera yenye masharti mengi. Unashughulikia hasa matatizo ya ushahidi usiotosha, majibu yasiyo na msingi wa kutosha, na maswali changamano ambayo hayawezi kukamilishwa kwa utafutaji mmoja. Sehemu ya nyuma inaendeshwa na FastAPI na LangGraph, huku sehemu ya mbele ikitumia React. Mfumo unaweza kuchagua kwa nguvu njia kati ya jibu la moja kwa moja, utafutaji wa maarifa, utafutaji wa ziada, utekelezaji wa zana, uthibitishaji wa binadamu na kukataa jibu, kulingana na nia ya mtumiaji na ugumu wa swali.

Mradi unafaa kwa maonyesho ya ndani, kujifunza mtiririko wa kazi wa Adaptive RAG na uthibitishaji wa uhandisi. Unaunga mkono kunukuu vyanzo vya sera, utafutaji wa oda za maonyesho, shughuli zinazosubiri uthibitisho, kumbukumbu za mazungumzo na majibu ya SSE, lakini data ya oda na usafirishaji si data halisi ya biashara.

Kwa sasa API inapokea moja kwa moja user_id kutoka kwa mteja, bila kuthibitisha utambulisho wake halisi. Usisambaze mradi moja kwa moja kwenye mtandao wa umma bila kuunganisha uthibitishaji wa utambulisho unaoaminika, TLS na udhibiti wa ufikiaji.

Jinsi Mfumo Unavyoshughulikia Ombi

Baada ya mtumiaji kuwasilisha swali kupitia ukurasa wa Web au HTTP API, ombi hupitia mfululizo wa ulinzi wa ingizo, utambuzi wa nia na upangaji kulingana na ugumu. Mfumo huchagua tawi linalofaa la uchakataji, kisha hukamilisha uundaji wa jibu, ukaguzi wa uaminifu, usasishaji wa kumbukumbu ya mazungumzo na urejeshaji wa marejeo.

Mtumiaji → Web / HTTP API → Ulinzi wa ingizo
          → Utambuzi wa nia → Upangaji wa ugumu
            ├─ Jibu la moja kwa moja
            ├─ Utafutaji → Upangaji bora → Utafutaji wa ziada inapohitajika
            ├─ Upangaji → Utekelezaji wa zana / Uthibitishaji wa binadamu
            └─ Kukataa jibu
          → Uundaji na ukaguzi wa uaminifu → Kumbukumbu ya mazungumzo → Jibu na marejeo

Utambuzi wa nia unaweza kutumia DeepSeek ya kawaida au kubadilishwa kuwa TypeSafe Jev. Kumbuka kuwa Jev hubadilisha tu nodi ya uainishaji wa nia; nodi nyingine za LLM, zikiwemo uamuzi wa ugumu, uandishi upya wa hoja ya utafutaji, upangaji wa kazi, uundaji wa jibu, ukaguzi wa uaminifu na muhtasari wa kumbukumbu, bado zinaendeshwa na DeepSeek.

Uwezo Mkuu

• Upangaji unaobadilika: Huchanganya nia ya biashara na ugumu wa swali ili kuchagua jibu la moja kwa moja, utafutaji wa mzunguko mmoja, utafutaji wa mizunguko mingi, utekelezaji wa zana au kukataa jibu.
• Utafutaji mseto: Huchanganya urejeshaji wa BM25 na vekta mnene, hutumia RRF kuunganisha matokeo na inaweza kuwezesha upangaji bora kwa Cross-Encoder.
• Kuimarisha ushahidi: Inaunga mkono uandishi upya wa hoja ya utafutaji, utafutaji wa ziada wakati ushahidi hautoshi, ukaguzi wa uaminifu wa jibu na kujisahihisha.
• Sehemu mbili za nyuma za nia: Kwa kawaida hutumia DeepSeek, na pia inaweza kutumia kiolesura cha choice kilichopangwa cha Jev kutambua aina 14 zilizofafanuliwa awali za nia za biashara.
• Uchakataji wa nyaraka: Inaunga mkono Markdown moja kwa moja; baada ya kusakinisha vitegemezi vya hiari na zana za mfumo, inaweza kuchanganua nyaraka za PDF, Office na OCR.
• Kugawa kwa muundo: Maandishi ya kawaida hutumia dirisha la herufi 500 na mwingiliano wa herufi 60 kwa chaguo-msingi; majedwali yanayotambuliwa hugawanywa kivyake huku yakihifadhi metadata kama kichwa, sura na chanzo.
• Zana za biashara: Hutoa zana za maonyesho zinazohusiana na oda, zikiwa na ukaguzi wa ruhusa, mpango wa kushuka kiwango, uthibitishaji wa binadamu na utaratibu wa idempotency, na pia inaweza kuunganisha zana za MCP.
• Uwezo wa uhandisi: Unajumuisha kubana kumbukumbu za mazungumzo, kumbukumbu zilizopangwa, vipimo vya Prometheus, ukaguzi wa afya na majaribio ya kiotomatiki.

Kuandaa Mazingira ya Uendeshaji

Mahitaji ya Msingi

• Python 3.11 au toleo jipya zaidi.
• Ikiwa unahitaji kuendesha sehemu ya mbele ya Web, tumia Node.js 20.19+ au 22.12+ na uwe na npm.
• Hali ya ndani ya chaguo-msingi hutumia SQLite na vipengele vya utafutaji vya kumbukumbu, kwa hiyo haihitaji Docker kuwashwa mapema.

Hatua za Usakinishaji katika Windows PowerShell

Baada ya kuiga hazina na kuingia kwenye saraka ya mzizi wa mradi, tengeneza mazingira pepe, sakinisha vitegemezi vya uundaji, nakili faili ya usanidi na tengeneza data ya maonyesho:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demo

Ikiwa .env tayari ipo kwenye saraka ya mzizi wa mradi, hifadhi faili hiyo na ruka amri ya kunakili. Kisha washa FastAPI:

.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

macOS na Linux

Kwenye macOS au Linux, unaweza kutengeneza na kuwasha mazingira pepe, kisha utekeleze amri zinazolingana za usakinishaji:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

Kuunda Miundo na Huduma za Ndani

Fungua .env kwenye saraka ya mzizi wa mradi. Mipangilio ifuatayo inafaa kukaguliwa kwanza:

• DEEPSEEK_API_KEY: Huwezesha mtiririko wa kazi wa DeepSeek na uainishaji wa nia wa chaguo-msingi. Miito halisi ya API inaweza kugharimu.
• INTENT_BACKEND: Inaweza kuwekwa kuwa deepseek ya chaguo-msingi au jev ya hiari.
• JEV_API_KEY: Inahitajika wakati wa kuwezesha uainishaji wa nia wa Jev.
• JEV_MODEL: Thamani ya sasa ya chaguo-msingi ya mradi ni jev-1.13.0.
• DATABASE_URL: Kwa chaguo-msingi hutumia sqlite+aiosqlite:///./data/local/app.db.
• KNOWLEDGE_DIR: Thamani ya chaguo-msingi ni knowledge; nyaraka za maarifa ndani yake huingizwa kwenye hifadhidata wakati wa kuwasha.
• LOCAL_EMBEDDING_ENABLED: Hudhibiti kipengele cha vekta za maana za ndani.
• CROSS_ENCODER_ENABLED: Hudhibiti kipengele cha upangaji bora wa ndani.
• REDIS_URL na QDRANT_URL: Husanidi huduma za hiari za nje za akiba na vekta.

Bila kusanidi ufunguo wa DeepSeek, mfumo bado unaweza kutumia mantiki ya maonyesho ya nje ya mtandao, lakini ubora wa majibu utatofautiana na hali ya modeli halisi. Vigezo vyote vinaweza kuonekana katika marejeo ya usanidi na faili ya mfano ya mazingira.

Washa Kiolesura cha Mazungumzo cha React

Endelea kuendesha mchakato wa sehemu ya nyuma, kisha kwenye kituo kingine ingia kwenye saraka ya sehemu ya mbele:

cd frontend
npm ci
npm run dev

Tembelea http://127.0.0.1:5173 ili kufungua ukurasa wa mazungumzo. Seva ya uundaji itaelekeza maombi ya /api kwenye mlango wa 8000 wa kompyuta hii.

Sehemu ya mbele inaunga mkono marejeo ya vyanzo, orodha za mazungumzo ya ndani na kadi za uthibitishaji wa shughuli. Baada ya jibu kuthibitishwa, sehemu ya nyuma hutuma maudhui kwa vipande kupitia SSE. Ukiendesha npm run build na kutengeneza frontend/dist, FastAPI itakapogundua saraka hiyo itatoa ukurasa wa sehemu ya mbele kutoka kwenye njia ya mzizi.

Matumizi ya Msingi: Kuuliza Sera ya Kurejesha au Kubadilisha Bidhaa

Kwanza thibitisha hali ya huduma:

• Nyaraka shirikishi za API
• Ukaguzi wa afya ya mchakato
• Ukaguzi wa utayari wa vitegemezi

Ifuatayo inatumia PowerShell kuwasilisha swali lenye masharti mengi ya sera kwenye kiolesura cha mazungumzo:

$payload = @{
    message = "定制马克杯过了七天，但是有质量问题，可以退吗？"
    user_id = "u_demo"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8000/api/v1/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($payload))

Mfumo kwanza utatambua nia inayohusiana na kurejesha au kubadilisha bidhaa, kisha uamue kulingana na ugumu wa swali ikiwa unahitaji kutafuta nyaraka za sera. Ikiwa ushahidi wa awali hautoshi, mtiririko wa kazi unaweza kuandika upya hoja ya utafutaji na kufanya utafutaji wa ziada; baada ya kuunda jibu, utakagua pia ikiwa jibu linaendana na ushahidi uliotafutwa na kurudisha marejeo ya vyanzo vinavyopatikana.

Pamoja na HTTP API, unaweza pia kutekeleza amri ifuatayo wakati sehemu ya nyuma inaendelea kufanya kazi, ukitumia mteja wa kituo:

python -m app.cli

Matumizi ya Msingi: Kuuliza na Kuendesha Oda za Maonyesho

scripts.seed_demo huunda oda za maonyesho kwa uwazi. Kuanzisha API pekee hakutaandika data hii kiotomatiki, kwa hiyo usiruke uanzishaji wa data wakati wa kuendesha mara ya kwanza. Mtumiaji wa maonyesho ni u_demo, na oda zinazopatikana ni:

• ORD10001: Imetumwa, bidhaa ni vipokea sauti vya kuzuia kelele.
• ORD10002: Imepokelewa, bidhaa ni kikombe maalum.
• ORD10003: Imelipiwa lakini bado haijatumwa, bidhaa ni T-shirt.

Kwa mfano, kwenye ukurasa wa mazungumzo ingiza 取消订单 ORD10003. Mfumo unapoendesha shughuli inayohitaji uthibitisho, unaweza kurudisha pending_action. Ombi la uthibitishaji lazima lirudishe session_id iliyo kwenye jibu, na liweke pending_action.action_id kwenye confirm_action_id. Ukurasa wa Web utatumia kadi ya uthibitishaji kusaidia kukamilisha mchakato huu.

Shughuli zinazosubiri uthibitisho huhifadhiwa kwa chaguo-msingi ndani ya mchakato wa seva kwa dakika 15. Baada ya seva kuwashwa upya au ombi kuhamia kwenye mchakato mwingine, huenda ukahitaji kuanzisha shughuli hiyo tena. Kwa maelezo ya sehemu mahususi na muundo wa kiolesura, rejelea marejeo ya API.

Usanidi wa Juu: Kuwezesha Utambuzi wa Nia wa Jev

Ili kubadilisha nodi ya uainishaji wa nia kuwa TypeSafe Jev, ongeza au badilisha usanidi ufuatao kwenye .env ya ndani:

INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true

DEEPSEEK_API_KEY=your_deepseek_api_key

Hifadhi kisha uwashe upya sehemu ya nyuma. Jev huunganishwa kupitia kiolesura cha HTTP na haihitaji kusakinisha SDK maalum. Matokeo yanayorejeshwa hukaguliwa na Pydantic kisha kubadilishwa kuwa matokeo ya uainishaji yaliyounganishwa.

Ufunguo wa Jev unapokosekana, ombi linaposhindikana au jibu linapokuwa si halali, mfumo hurudi kwenye IntentClassifier ya awali. Msururu wa kurejea nyuma hutumia kwanza DeepSeek iliyosanidiwa; ikiwa uko nje ya mtandao au mwito wa modeli umeshindikana, huendelea kutumia uainishaji wa kanuni. Hitilafu zinazoweza kujaribiwa tena hutumia kusubiri kwa kiongezeko cha kielezo, na JEV_MAX_RETRIES katika utekelezaji wa sasa humaanisha idadi ya juu ya majaribio.

JEV_INTENT_APPLY_OVERLAY hudhibiti marekebisho ya kanuni baada ya Jev kuainisha kwa mafanikio, na huwashwa kwa chaguo-msingi. Chaguo hili halidhibiti tabaka la marekebisho la kiainishaji cha kurejea nyuma chenyewe. Ili kurejesha uainishaji wa nia wa chaguo-msingi, badilisha tu INTENT_BACKEND kuwa deepseek.

Usanidi wa Juu: Utafutaji Ulioimarishwa na Uchanganuzi wa Nyaraka

Inasakinisha vitegemezi vya vekta za ndani na upangaji upya

.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"

Vitegemezi vya rerank hutumika kwa modeli ya ndani ya vekta mnene na Cross-Encoder. Modeli chaguomsingi ya vekta ni BAAI/bge-small-zh-v1.5, na modeli chaguomsingi ya upangaji upya ni BAAI/bge-reranker-base. Wakati wa upakiaji wa kwanza, uzani wa modeli unaweza kupakuliwa; modeli isipopatikana, mfumo utatumia hali ya chini, hivyo matokeo hayawezi kuwa sawa na usanidi kamili wa modeli.

Inasakinisha vitegemezi vya ziada vya uchanganuzi wa nyaraka

.\.venv\Scripts\python.exe -m pip install -e ".[docs]"

Vitegemezi vya docs hutumika kwa uchanganuzi wa nyaraka wa Unstructured. Wakati wa kuchakata faili za PDF, OCR na Office, huenda ukahitaji pia kusakinisha Poppler, Tesseract pamoja na kifurushi cha lugha ya Kichina, na LibreOffice. Mahitaji ya kina yanapatikana katika Maelezo ya uchanganuzi na utafutaji.

Vitambulisho vya vipande vya maarifa huundwa kulingana na njia ya hati na nambari ya kipande. Njia na matokeo ya kugawa vipande yasipobadilika, kuingiza data tena kunaweza kudumisha vitambulisho vilevile; baada ya kuhamisha faili, kuhariri maudhui au kubadilisha mkakati wa kugawa vipande, marejeleo ya zamani hayahakikishiwi kuendelea kuelekeza kwenye maudhui yale yale.

Kuanzisha huduma kamili kwa Docker

Ikiwa ungependa kuendesha API, PostgreSQL, Redis, Qdrant na frontend ya Web iliyojengwa kwa pamoja, kwanza andaa .env ya ndani, kisha endesha:

docker compose up --build

Baada ya kuanza, tembelea http://127.0.0.1:8000. Nenosiri la hifadhidata na uchoraji wa milango katika Compose vimekusudiwa maonyesho ya ndani pekee. Kabla ya kusambaza kwenye mtandao wa umma, lazima ubadilishe nenosiri la maonyesho, uzuie milango ya hifadhidata na akiba, uwashe uthibitishaji wa utambulisho unaoaminika na TLS, na ubuni mpango wa kuaminika wa uhifadhi wa kudumu na uendeshaji.

Majaribio, ukaguzi tuli na tathmini

Endesha majaribio ya backend na ukaguzi wa ubora katika saraka kuu ya mradi:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrieval

Majaribio ya frontend na amri za kujenga lazima zitekelezwe katika saraka ya frontend:

npm test
npm run build

Usanidi wa majaribio hutenga funguo za modeli za ndani na hutumia hifadhidata ya majaribio. Kabla ya kuendesha tathmini ya modeli halisi peke yake, kagua usanidi wa modeli na mtandao, kwa kuwa kuita modeli za nje kunaweza kugharimu fedha.

Kulinganisha uainishaji wa nia wa Jev na DeepSeek

Baada ya kusanidi funguo za ndani za modeli hizo mbili, unaweza kuendesha ulinganisho kwa kutumia sampuli na masharti yale yale ya overlay:

.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.json

Ripoti inajumuisha usahihi, ucheleweshaji wa P50 na P95, idadi ya urejeshaji wa nyuma na idadi ya matumizi ya sheria. --no-overlay huzima marekebisho ya sheria kwa waainishaji wote wawili, ili kurahisisha kuona matokeo ya uainishaji ya modeli zenyewe; ukiondoa kigezo hicho, unaweza kulinganisha matokeo baada ya kuongeza overlay.

Seti ya sasa ya data ya nia ni seti ya maendeleo; usahihi wake unajumuisha sampuli zilizorejeshwa nyuma, hivyo hauwezi kuchukuliwa moja kwa moja kuwa uwezo wa jumla wa modeli huru ya Jev. Tathmini za kihistoria pia hazimaanishi kuwa toleo la sasa limethibitishwa upya, wala si dhamana ya matokeo halisi ya biashara.

Mapendekezo ya vitendo ya uhandisi

1. Thibitisha mtiririko kwanza kwa hali chaguomsingi ya ndani: SQLite na vipengele vya utafutaji vya kumbukumbu vinatosha kukamilisha onyesho la msingi; si lazima uanze kwa kusambaza hifadhidata na huduma ya vekta za nje.
2. Tenganisha modeli ya nia na modeli za mtiririko wa kazi: Kubadilisha kwenda Jev hakutabadilisha nodi nyingine za DeepSeek. Ikiwa ungependa kuendesha mtiririko kamili wa kazi mtandaoni, bado utahitaji kusanidi DeepSeek.
3. Tumia endpoint za afya kutafuta matatizo: /api/v1/health hutumika kukagua mchakato, ilhali /api/v1/ready inafaa zaidi kuthibitisha kuwa vitegemezi viko tayari.
4. Badilisha mkakati wa kugawa vipande kwa uangalifu: Mabadiliko ya njia, maudhui ya maandishi au vigezo vya kugawa vipande yanaweza kuathiri vitambulisho vya vipande na marejeleo ya zamani.
5. Usiegemee hali ya uthibitishaji iliyo ndani ya mchakato: Shughuli chaguomsingi zinazosubiri uthibitishaji huwa halali kwa dakika 15 pekee, na zinaweza kupotea kwa sababu ya kuwasha upya au kubadilisha michakato mingi.
6. Linda data nyeti: Usitumie GitHub kuwasilisha .env, funguo halisi, hifadhidata za ndani, kumbukumbu, nyaraka zilizopakiwa na watumiaji au taarifa binafsi.
7. Kagua uhamishaji wa data kwenda nje: Kabla ya kutumia modeli ya nje au MCP ya mbali, thibitisha kuwa maombi hayana taarifa za mtumiaji ambazo hazipaswi kutumwa nje.
8. Panga masasisho ya hifadhidata ya maarifa: Kwa sasa mfumo huingiza data yote wakati wa kuanza, na bado hautoi mchakato kamili wa kufuta data kwa nyongeza.

Muhtasari wa saraka za mradi

• app/api: API ya HTTP na SSE.
• app/agents: Grafu za utekelezaji za LangGraph na nodi za mtiririko wa kazi.
• app/retrieval: Uchanganuzi, ugawaji wa vipande, urejeshaji, uunganishaji na upangaji upya.
• app/providers: Adaptori za modeli na huduma za vekta.
• app/tools: Zana za biashara, usajili wa zana na udhibiti wa ruhusa.
• app/mcp: Muunganisho wa zana za MCP.
• app/memory: Kumbukumbu ya mazungumzo na ukandamizaji.
• app/guardrails: Ukaguzi wa ingizo na majibu.
• app/observability: Kumbukumbu na vipimo.
• frontend: Kiolesura cha mazungumzo cha React na TypeScript.
• knowledge: Nyaraka za maarifa ya sera.
• tests na eval: Majaribio ya kiotomatiki, data ya tathmini na zana za utekelezaji.

Hitimisho

Huduma ya wateja ya biashara ya mtandaoni ya Adaptive-RAG inaonyesha mnyororo kamili kiasi wa uhandisi wa huduma mahiri kwa wateja: kwanza hutambua nia na kutathmini uchangamano, kisha huunganisha kwa mahitaji utafutaji mseto, ukamilishaji wa ushahidi katika raundi nyingi, matumizi ya zana, uthibitishaji wa binadamu na ukaguzi wa uaminifu. Unaweza kuanza kwa kutumia SQLite, maagizo ya maonyesho na mantiki ya nje ya mtandao kwa uzoefu wa haraka, kisha kuwezesha hatua kwa hatua DeepSeek, Jev, modeli za ndani za vekta, Cross-Encoder, uchanganuzi wa ziada wa nyaraka na huduma za Docker.

Kabla ya kuingia katika biashara halisi, bado unahitaji kukamilisha hasa uthibitishaji wa utambulisho, muunganisho wa mfumo halisi wa maagizo, uhifadhi wa kudumu wa hali ya uthibitishaji, matengenezo ya nyongeza ya hifadhidata ya maarifa, usimamizi wa funguo na usalama wa mtandao wa kiwango cha uzalishaji. Mradi unatumia MIT License; maelezo zaidi kuhusu usanifu na vikwazo yanapatikana katika Usanifu na mtiririko wa uendeshaji, Muundo wa utafutaji na Vikwazo na ramani ya barabara.