Zbuduj amerykański analizator pism urzędowych z Qwen4-Max, Qwen-Agent i Olostep. Oznaczaj oszustwa, czytaj zdjęcia i PDF-y, weryfikuj twierdzenia w oficjalnych źródłach.
Czy zdarzyło ci się dostać pismo „od rządu” i zastanawiać się, czy jest prawdziwe, czy musisz odpowiadać, czy może ktoś próbuje cię oszukać?
Pisma urzędowe są trudne w lekturze, zwłaszcza gdy zawiły język miesza się z żądaniami płatności i terminami. Oszuści wykorzystują to zamieszanie, podszywając się pod urzędy i wywołując fałszywe poczucie pilności.
W tym samouczku zbudujemy amerykański analizator pism urzędowych z użyciem Qwen4-Max i frameworka Qwen-Agent. Aplikacja przyjmuje tekst, obrazy i PDF-y, oznacza podejrzane taktyki płatnicze oraz przeszukuje oficjalne źródła prawne, gdy trzeba coś zweryfikować.
Zamiast polegać wyłącznie na dużym modelu językowym (LLM), połączymy go z dwoma narzędziami w Pythonie. Pierwsze używa wyrażeń regularnych do wykrywania typowych oznak oszustwa. Drugie korzysta z Olostep do przeszukiwania oficjalnych stron rządowych i Cornell Legal Information Institute (LII).
W skrócie
Budujemy analizator pism urzędowych z Qwen4-Max, Qwen-Agent i Olostep, który przyjmuje tekst, zdjęcia i PDF-y.
Bramka ryzyka oparta na regexach oznacza wzorce oszustw i domeny‑sobowtóry, zanim model zacznie badania.
Narzędzie badawcze ogranicza wyszukiwanie do stron .gov i Cornell LII, a agent pomija badania, gdy pismo jest ewidentnie fałszywe.
W moich testach Qwen4-Max dobrze czytał sfotografowane pisma, ale był wolny przy prostych zadaniach, a jego natywne wyszukiwanie w sieci było zawodne.
Czym jest Qwen4-Max?
Qwen4-Max to flagowy model Alibaby z rodziny Qwen4, wprowadzony 16 listopada 2026 r. To rzadki model mixture-of-experts (MoE) z ulepszeniami architektury, natywną wizją i większym kontekstem, zaprojektowany do złożonego rozumowania i aplikacji agentskich.
Najważniejsze cechy dla naszego projektu:
Rzadka architektura MoE: Qwen4-Max ma 2,4T parametrów rdzeniowych, 71B aktywnych na token i dodatkowe 328B parametrów osadzania N-gram. Warstwy Gated DeltaNet i Qwen Sparse Attention ograniczają koszty długiego kontekstu.
Natywna wizja: Model czyta obrazy bezpośrednio, więc możemy wysłać zdjęcie pisma bez budowania osobnej ścieżki OCR.
Kontekst 1M tokenów: Wystarczający dla długich dokumentów i wielu informacji pomocniczych.
Lepsza efektywność tokenów: Według Alibaby, Qwen4-Max zużywa ok. 35% mniej tokenów niż Qwen3.8-Max na Work360 przy wysiłku reasoning „High”, i ok. 49% mniej na Terminal-Bench 4.0. Przy „Xhigh” redukcje to ok. 24% i 48%.
Niższe koszty zadań: Na Work360 Qwen4-Max uzyskał 52,69 (vs 47,74 dla Qwen3.8-Max), a średni koszt na zadanie spadł z 4,43 USD do 1,67 USD, czyli o 62%.
Oto wyniki benchmarków z ogłoszenia Alibaby, pokazujące, że Qwen4-Max poprawia wyniki Qwen3.8-Max w niemal każdej ocenianej kategorii:
Analizator to pojedynczy asystent Qwen-Agent, który koordynuje dwa narzędzia w Pythonie, a Qwen4-Max odpowiada za rozumienie dokumentów i wnioskowanie. Zanim napiszemy kod, spójrzmy na przepływ pracy.
Rysunek 2: Przepływ pracy analizatora pism.
Przepływ ma 6 kroków:
Użytkownik przesyła pismo jako tekst, obraz lub PDF.
Qwen4-Max czyta dokument i identyfikuje jego główne treści.
Agent wywołuje risk_gate, by sprawdzić podejrzane instrukcje płatności, groźby i linki.
Jeśli dokument jest oczywiście fałszywy, agent pomija badania zewnętrzne.
W przeciwnym razie agent wywołuje lookup_law, aby przeszukać oficjalne źródła prawne.
Qwen4-Max tworzy ustrukturyzowaną odpowiedź z werdyktem, podsumowaniem, dowodami i zalecanymi krokami.
Kluczowa decyzja projektowa: LLM nie robi wszystkiego. Python obsługuje deterministyczne sprawdzenia, Olostep – badania zewnętrzne, a Qwen4-Max – rozumienie dokumentu i wnioskowanie.
To utrzymuje prostotę, a jednocześnie daje agentowi odpowiednie narzędzia do każdej części zadania. Jeśli terminologia agentska jest ci nowa, nasz kurs Introduction to AI Agents omawia podstawy bez kodowania.
1. Przygotowanie środowiska
Użyjemy Jupyter Notebook, QwenCloud do dostępu do modelu i Olostep do wyszukiwania i scrapowania sieci.
Najpierw utwórz konto w QwenCloud, doładuj środki lub wykup Token Plan i wygeneruj klucz API w panelu. QwenCloud udostępnia endpoint API na podstawie wybranego regionu.
Ustaw zmienne środowiskowe w terminalu przed uruchomieniem Jupyter Notebook. Możesz też ustawić je w notebooku przez os.environ.
exportQWEN_API_KEY="your-qwen-api-key"exportQWEN_BASE_URL="https://token-plan.maas.qwencloudapi.com/compatible-mode/v1"exportOLOSTEP_API_KEY="your-olostep-api-key"Obsługiwane przez
Używam endpointu Token Plan, który daje tańszy dostęp do modeli. Jeśli płacisz w modelu PAYG, użyj endpointu pokazywanego przez QwenCloud dla twojego regionu.
Następnie zainstaluj wymagane zależności w notebooku:
%pip install -q "qwen-agent[rag]" olostep soundfile tqdmObsługiwane przez
Dodatek rag instaluje pakiety do przetwarzania dokumentów, takie jak pdfplumber, którego użyjemy do odczytu PDF-ów. Od wersji 0.0.34 Qwen-Agent importuje też soundfile i tqdm przy starcie bez deklarowania ich jako zależności, więc instalujemy je jawnie.
Konfiguracja Qwen4-Max
Teraz inicjalizujemy model i klienta Olostep. Używam regionu Singapur, który również oferuje Token Plan.
import logging
import os
import re
import warnings
# The Olostep SDK reads this at import time, so set it first
os.environ.setdefault("OLOSTEP_API_TIMEOUT","40")from olostep import Olostep
from qwen_agent.agents import Assistant
from qwen_agent.llm.schema import Message
from qwen_agent.tools.base import BaseTool
from qwen_agent.utils.utils import extract_text_from_message
warnings.filterwarnings("ignore")
logging.getLogger("qwen_agent_logger").setLevel(logging.ERROR)
MODEL = os.getenv("QWEN_MODEL","qwen4-max")
LLM ={"model": MODEL,"model_type":"qwenvl_oai","model_server": os.environ["QWEN_BASE_URL"],"api_key": os.environ["QWEN_API_KEY"],"generate_cfg":{"max_tokens":3000,"extra_body":{"reasoning_effort":"low"},},}
olostep = Olostep(api_key=os.environ["OLOSTEP_API_KEY"])Obsługiwane przez
To konfiguruje Qwen4-Max dla wejścia multimodalnego, ustawia poziom wysiłku rozumowania i inicjalizuje klienta badań. Zauważ, że OLOSTEP_API_TIMEOUT ustawiamy przed importem, bo SDK odczytuje to przy ładowaniu.
Warto znać kilka opcji konfiguracyjnych:
model określa model, którego chcemy użyć.
model_type pozwala wysyłać obrazy przez interfejs multimodalny zgodny z OpenAI.
model_server wskazuje endpoint z QWEN_BASE_URL.
max_tokens ogranicza długość generowanej odpowiedzi.
reasoning_effort kontroluje ilość rozumowania modelu. Używamy low, by utrzymać szybkość.
OLOSTEP_API_TIMEOUT ustawia limit czasu (s) na zapytania badawcze.
Tworzenie pomocników agenta do ponownego użycia
Będziemy przetwarzać zarówno tekst, jak i obrazy, więc stwórzmy funkcję do uruchamiania agenta.
defrun_agent(agent, prompt, images=None):
content =[{"text": prompt}]+[{"image": image}for image in(images or[])]
final = agent.run_nonstream([{"role":"user","content": content}])return extract_text_from_message(
Message.model_validate(final[-1]),
add_upload_info=False,)Obsługiwane przez
Funkcja wysyła prompt i opcjonalne obrazy do Qwen-Agent, czeka na odpowiedź końcową i wyodrębnia wygenerowany tekst.
Potrzebujemy też pomocnika do odczytu PDF-ów.
defread_pdf(path):import pdfplumber
with pdfplumber.open(path)as pdf:return"\n".join(
page.extract_text()or""for page in pdf.pages
)Obsługiwane przez
Funkcja wyciąga zaznaczalny tekst z każdej strony PDF i łączy go w jeden ciąg.
Uwaga: pdfplumber nie wykonuje OCR. Dla skanowanych PDF-ów zawierających tylko obrazy wyrenderuj każdą stronę jako obraz i wyślij bezpośrednio do Qwen4-Max.
2. Wykrywanie oszustw bramką ryzyka
Pierwsze narzędzie wykrywa podejrzane zachowania. Zamiast prosić LLM o rozpoznanie każdej podejrzanej instrukcji płatności, użyjemy wyrażeń regularnych do wykrywania znanych taktyk.
To szybsze, deterministyczne i nie zużywa tokenów modelu. Jeśli chcesz odświeżyć składnię, zajrzyj do naszego kursu Regular Expressions in Python.
Definiowanie reguł wykrywania oszustw
Zacznijmy od listy wyrażeń regularnych i mapowania między agencjami rządowymi a ich oficjalnymi domenami.
RULES =[("gift cards",r"\b(gift\s*cards?|itunes|google play|amazon card)\b"),("crypto",r"\b(bitcoin|btc|usdt|crypto\w*|coinbase|binance)\b"),("wire transfer",r"\b(wire transfer|western union|moneygram)\b"),("payment app",r"\b(zelle|venmo|cash app|paypal)\b"),("arrest threat",r"\b(arrest|warrant|deport\w*)\b"),("extreme urgency",r"\b(within 24 hours|final notice|last chance)\b"),("secrecy",r"\b(do not (tell|discuss|contact)|keep this confidential)\b"),("card numbers by phone",r"\bcard numbers?\b"),("qr or crypto atm",r"\b(qr code|bitcoin atm|crypto atm)\b"),]
OFFICIAL ={"irs":"irs.gov","internal revenue":"irs.gov","ftc":"ftc.gov","cfpb":"consumerfinance.gov","social security":"ssa.gov","uscis":"uscis.gov","justice":"justice.gov","hud":"hud.gov","uscourts":"uscourts.gov",}
URL_RX = re.compile(r"https?://[^\s)\"'<>]+")Obsługiwane przez
Ten kod definiuje wskaźniki oszustw i mapuje nazwy agencji na domeny, których naprawdę używają. Np. jeśli pismo wspomina IRS, aplikacja sprawdza linki względem irs.gov.
Wyodrębnianie i weryfikacja domen
Potrzebujemy teraz pomocnika do wyodrębniania hosta z URL-a.
from urllib.parse import urlparse
defhost_of(url):return(urlparse(url).hostname or"").lower().rstrip(".")defis_official_domain(host, domain):return host == domain or host.endswith("."+ domain)Obsługiwane przez
To wyciąga nazwę hosta i sprawdza, czy to oficjalna domena lub legalna subdomena. To ważne rozróżnienie: proste endswith() zaakceptowałoby fakeirs.gov jako stronę IRS.
Implementacja narzędzia bramki ryzyka
Teraz możemy połączyć te reguły w niestandardowe narzędzie Qwen-Agent.
classRiskGate(BaseTool):
name ="risk_gate"
description =("Scan a notice for payment tactics, threats, urgency, ""secrecy, and suspicious agency links. ""Call once before any other tool.")
parameters ={"type":"object","properties":{"text":{"type":"string","description":("The full notice text, including links ""and payment instructions."),}},"required":["text"],}defcall(self, params,**kwargs):
text = self._verify_json_format_args(params)["text"]
low = text.lower()
flags =[f"scam indicator: {label}"for label, pattern in RULES
if re.search(pattern, low)]
agency =next((
domain
for word, domain in OFFICIAL.items()if re.search(rf"\b{re.escape(word)}\b", low)),None,)if agency:
hosts ={
host_of(url)for url in URL_RX.findall(text)}
flags +=[f"lookalike domain: {host} is not {agency}"for host insorted(hosts)if host andnot is_official_domain(host, agency)]return"\n".join(flags)or"no flags"Obsługiwane przez
Narzędzie skanuje pismo pod kątem dopasowań, sprawdza jego URL-e względem oficjalnej domeny agencji i zwraca podejrzane wskaźniki. Nazwy agencji są dopasowywane jako całe słowa, więc „irs” nie zadziała na słowie „first”.
Na przykład nasz fikcyjny list IRS z Testu 1 daje:
scam indicator: gift cards
scam indicator: wire transfer
scam indicator: arrest threat
scam indicator: extreme urgency
scam indicator: secrecy
scam indicator: card numbers by phone
lookalike domain: irs-gov-payments.top is not irs.govObsługiwane przez
Agent otrzymuje te wyniki w swoim kontekście i wykorzystuje je przy ocenie, czy pismo jest podejrzane.
3. Tworzenie narzędzia do badań prawnych
Drugie narzędzie obsługuje badania zewnętrzne. Nie chcemy, by agent przeszukiwał losowe strony, fora czy blogi kancelarii i traktował wszystko jak autorytatywne.
Zamiast tego ograniczamy badania do oficjalnych stron rządu USA i Cornell LII. Użyjemy Olostep, bo potrafi wyszukać i zeskrobać wiele wyników w jednym żądaniu. Jeśli chcesz porównać z inną opcją, zobacz nasz samouczek Firecrawl.
Definiowanie ograniczeń badań
Najpierw określmy dozwolone źródła i limity tego, co pobieramy.
defis_allowed_host(host):return host.endswith(".gov")or is_official_domain(
host,"law.cornell.edu")
MAX_PAGES =2
PAGE_CHARS =3000Obsługiwane przez
Funkcja is_allowed_host() akceptuje strony .gov i Cornell LII. Wykorzystuje is_official_domain(), więc sobowtóry typu fakelaw.cornell.edu są odrzucane. Zachowujemy co najwyżej 2 strony, maks. 3000 znaków na stronę.
Implementacja narzędzia LookupLaw
Teraz stwórzmy drugie narzędzie niestandardowe.
classLookupLaw(BaseTool):
name ="lookup_law"
description =("Search for official US legal guidance using ""government websites and Cornell LII. ""Return the most relevant page excerpts.")
parameters ={"type":"object","properties":{"query":{"type":"string","description":"One plain-English legal question.",},"domain":{"type":"string","description":"Optional domain, such as irs.gov.",},},"required":["query"],}def__init__(self):super().__init__()
self.sources =[]defcall(self, params,**kwargs):
args = self._verify_json_format_args(params)
found = olostep.searches.create(
args["query"][:200],
limit=5,
include_domains=([args["domain"]]if args.get("domain")elseNone),
scrape_options={"formats":["markdown"],"timeout":20,},)
pages =[]for link in found.links:
host = host_of(link["url"])ifnot is_allowed_host(host):continue
body =(
link.get("markdown_content")or link.get("description")or"")[:PAGE_CHARS]if body:
self.sources.append(link["url"])
pages.append(f"### {link['url']}\n{body}")iflen(pages)== MAX_PAGES:breakreturn"\n\n".join(pages)or("No official page found. Results outside "".gov and Cornell LII are treated as unreliable. ""Try a shorter query with the statute or agency name.")Obsługiwane przez
Narzędzie wysyła zapytanie do Olostep, filtruje wyniki, wyciąga treści stron i zwraca wybrane fragmenty do Qwen4-Max.
Warte uwagi szczegóły implementacyjne:
Pobieramy do 5 wyników, ale zachowujemy najwyżej 2 kwalifikujące się strony.
Preferujemy zeskrobany Markdown, w razie potrzeby bierzemy opis strony.
Przechowujemy pobrane URL-e w self.sources, by aplikacja mogła je wyświetlić po analizie.
4. Budowa agenta z Qwen-Agent i Qwen4-Max
Mamy już oba narzędzia: risk_gate identyfikuje podejrzane zachowania, a lookup_law pobiera istotne informacje prawne. Teraz tworzymy agenta, który je koordynuje.
Pojedynczy prompt systemowy definiuje przepływ pracy, kolejność narzędzi i format odpowiedzi. Qwen-Agent nie jest jedyną opcją dla takiej budowy – nasz kurs Developing LLM Applications with LangChain omawia inny framework.
Definiowanie promptu systemowego
SYSTEM ="""You explain a US legal or government notice
to the person who received it, in plain English.
You are not a lawyer.
How to work:
- Read the notice, text or images. Report only what
the document actually says.
- Call risk_gate once with the notice text before
using any other tool.
- Treat risk_gate flags as evidence, not proof.
Flags can make a notice suspicious but cannot
establish that it is legitimate.
- If the notice is plainly fraudulent, say so and
skip research.
- Otherwise, call lookup_law with one plain question
about the main legal issue.
- Call lookup_law a second time only if the first
call returns no official page.
- Never invent a law, citation, phone number, amount,
or deadline.
- Report deadlines using the document's own words.
Separate a stated deadline from whether it is credible.
- If a returned page does not verify a claim,
explicitly say it could not be verified.
- Never suggest ignoring a legal notice.
- Separate what the document establishes from
what is assumed.
- Keep each section under 80 words.
- Use plain English, short sentences, and bullets.
- Avoid em dashes and contractions.
Begin with this verdict block:
**Scam:** yes, probably, or no
(confidence: low, medium, or high).
**Time sensitive:** yes or no, followed by the
exact deadline in the document, or "no deadline stated".
**Demand:** the amount and what the document asks
for, or "nothing is demanded".
Then write these sections in order:
### Summary
Explain what the document is and what happens
if nothing is done. Use 3 or 4 sentences.
### Evidence
Include one bullet per important finding.
Quote the document or the official page where
possible. Include risk_gate flags.
If the scan returned no flags, explicitly say so.
No flags is not proof that a notice is legitimate.
### Next steps
Give numbered actions in the order they should
be taken.
If the notice threatens eviction, foreclosure,
a lawsuit, arrest, or deportation, the first action
must be to contact a qualified attorney or legal aid.
Explain that waiting creates a risk.
Never confuse a document's claimed deadline with
a verified legal deadline.
Do not include a sources section or legal disclaimer.
The application appends both."""Obsługiwane przez
Ten prompt definiuje obowiązki agenta i powstrzymuje go przed wymyślaniem informacji prawnych. Jedna wskazówka wymaga uwagi: terminy.
Fałszywe pismo może zawierać termin, więc agent musi podać, co dokument twierdzi, a zarazem wyjaśnić, czy ten termin jest wiarygodny.
Dodanie zastrzeżenia i obsługi źródeł
Trzymamy zastrzeżenie poza promptem systemowym, aby Python mógł je spójnie dodawać.
NO_SOURCE =("No official page was retrieved for this notice, ""so treat any legal statement above as unverified.")
DISCLAIMER =("\n---\n""**Not legal advice.** Verify deadlines and citations ""with the issuing authority, using contact details ""you find independently, not those printed in the notice.")Obsługiwane przez
To daje wiadomość awaryjną, gdy badania nie zwrócą oficjalnego źródła, a każda odpowiedź ma zastrzeżenie prawne.
Tworzenie głównej funkcji analizy
Na koniec połączmy wszystko w jedną funkcję wielokrotnego użytku.
defanalyze_notice(text=None, images=None):
research = LookupLaw()
agent = Assistant(
llm=LLM,
system_message=SYSTEM,
function_list=[
RiskGate(),
research,],)
prompt =(f"Notice text:\n\n{text}"if text
else"The notice is attached as image files.")
answer = run_agent(agent, prompt, images)
sources ="\n".join(f"- {url}"for url in research.sources
)return(f"{answer}\n\n"f"## Sources\n\n"f"{sources or NO_SOURCE}\n"f"{DISCLAIMER}")Obsługiwane przez
Funkcja tworzy świeżego agenta dla każdego dokumentu, uruchamia analizę, zbiera pobrane źródła i zwraca finalną odpowiedź. Tworzymy LookupLaw() wewnątrz funkcji, by każde pismo miało własną listę źródeł.
5. Testowanie analizatora pism
Mamy już działający analizator pism. Przetestujmy go na 3 przykładach:
Fikcyjny list‑oszustwo od IRS.
Fotografia nakazu eksmisji z Florydy.
PDF z wezwaniem do zaniechania naruszeń.
Każdy test sprawdza inny element przepływu.
Test 1: List‑oszustwo IRS
Pierwszy przykład to fikcyjny list‑oszustwo IRS. Twierdzi, że odbiorca ma 4 870 USD zaległości w podatku dochodowym i musi zapłacić w ciągu 24 godzin.
Grozi też aresztem, żąda płatności kartami podarunkowymi lub przelewem i zawiera podejrzaną stronę. Oto wejście przykładowe:
from IPython.display import Markdown
FICTIONAL_NOTICE ="""
INTERNAL REVENUE SERVICE
NOTICE OF FINAL DEMAND
Date of Notice: November 10, 2026
Our records show an outstanding balance of
$4,870.00 in federal income tax for tax year 2024.
You must resolve this balance within 24 hours.
Failure to comply will result in a warrant for your
arrest and your wages being garnished.
Do not discuss this notice with anyone.
Pay using Apple or Google Play gift cards and
provide the card numbers over the phone, or by
wire transfer through:
https://irs-gov-payments.top/pay?ref=MW4471
""".strip()
Markdown(analyze_notice(text=FICTIONAL_NOTICE))Obsługiwane przez
To tworzy fikcyjne pismo i przekazuje je agentowi do analizy.
Wynik:
Rysunek 3: Wynik analizatora dla fikcyjnego listu‑oszustwa IRS.
Skaner znajduje kilka podejrzanych wskaźników, a agent pomija badania zewnętrzne. Tego oczekujemy przy oczywistym oszustwie: aplikacja nie wydaje dodatkowych tokenów na badania, gdy deterministyczne sprawdzenia już wskazują na fałsz.
Co pokazuje test: Bramka ryzyka potrafi wykrywać typowe taktyki oszustów i pomaga agentowi unikać zbędnych badań zewnętrznych.
Test 2: Fotografia nakazu eksmisji
Drugi test koncentruje się na natywnej wizji Qwen4-Max. Zamiast samodzielnie wyciągać tekst, wysyłamy bezpośrednio fotografię nakazu eksmisji do modelu.
Nasz przykład to 3‑dniowe zawiadomienie z Florydy z żądaniem 1 850 USD zaległego czynszu lub wydania nieruchomości do 23 listopada 2026 r. Oto kod:
Markdown(
analyze_notice(
images=["samples/eviction.png"]))Obsługiwane przez
To wysyła fotografię prosto do Qwen4-Max, więc nie potrzeba osobnej ścieżki OCR. Inny projekt łączący wizję Qwen z wywołaniem narzędzi znajdziesz w naszym samouczku API Qwen 3.6 Plus o przetwarzaniu faktur.
Wynik:
Rysunek 4: Wynik analizatora dla sfotografowanego nakazu eksmisji.
Model zrozumiał fotografię, wyciągnął kwotę i termin oraz rozpoznał typ pisma. Zaznaczył, że pobrana strona prawna nie zawierała wystarczających informacji do weryfikacji przepisu i zauważył puste pola podpisu oraz doręczenia w przykładzie.
Co pokazuje test: Qwen4-Max potrafi bezpośrednio interpretować sfotografowane dokumenty prawne, a Qwen-Agent koordynuje dodatkowe badania i komunikuje niepewność.
Test 3: PDF z wezwaniem do zaniechania naruszeń
W ostatnim teście używamy dwustronicowego pisma „cease and desist” w PDF.
Dokument cytuje 17 U.S.C. §§ 501 i 512, zarzuca naruszenie praw autorskich i prosi o usunięcie spornych treści oraz potwierdzenie do 28 listopada 2026 r. PDF zawiera zaznaczalny tekst, więc możemy użyć pomocnika read_pdf(). Oto kod:
pdf_text = read_pdf("samples/legal.pdf")
Markdown(
analyze_notice(text=pdf_text))Obsługiwane przez
To wyciąga zawartość PDF i wysyła tekst do tego samego agenta.
Wynik:
Rysunek 5: Wynik analizatora dla pisma „cease and desist”.
Agent trafnie odróżnia prywatne żądanie prawne od oficjalnego pisma urzędu lub sądu. Rozpoznaje, że nie ma żądania pieniędzy, i dostosowuje rekomendacje. Narzędzie badawcze pobrało odpowiednią stronę US Copyright Office, która pojawia się w źródłach.
Co pokazuje test: Ten sam agent potrafi obsłużyć korespondencję PDF, zidentyfikować charakter żądania prawnego i zaproponować odpowiednie kolejne kroki.
Moje doświadczenia z Qwen4-Max: plusy, minusy i zgrzyty
Po użyciu Qwen4-Max w tym projekcie, innych aplikacjach agentskich i „vibe codingu”, oto moja szczera ocena.
Plusy
Ekosystem Qwen obejmuje wiele obszarów. Oferuje rozpoznawanie mowy, syntezę mowy, wyszukiwanie w sieci, scrapowanie oraz otwarte narzędzia do budowy aplikacji agentskich bez zaczynania od zera.
Najbardziej podobało mi się, jak dobrze Qwen4-Max stosował się do szczegółowych instrukcji. Zwykle respektował żądany format wyjścia, wyciągał daty z dokumentów i tworzył trafne podsumowania w moich testach.
Wyróżniało się rozumienie obrazów. Podałem mu fotografię pisma i odczytał treść bez dodatkowego OCR, co bardzo pomaga w aplikacjach agentskich pracujących z dokumentami.
Minusy
Prędkość była dla mnie największym problemem. Qwen4-Max nie był moim wyborem do „vibe codingu”: w porównaniu z DeepSeek V4.1 Flash i innymi testowanymi modelami często zauważalnie dłużej kończył proste zadania.
Regularnie widziałem tempo generacji ok. 100 tokenów/s, ale to ukrywa realny koszt. Model długo rozumował nad prostymi zmianami, a czasem prosiłem o drobną edycję i czekałem znacznie dłużej niż oczekiwałem.
Najbardziej frustrujące było natywne wyszukiwanie w sieci. W moich testach czasy odpowiedzi były niespójne: to samo zapytanie wracało w sekundy albo trwało prawie minutę, a niektóre żądania przekraczały 400 s i nie kończyły się.
Trzy uruchomienia mojego przepływu badań zajęły prawie 16 minut. To za mało niezawodne dla aplikacji, która polega na zewnętrznych informacjach prawnych.
Zastąpienie natywnego wyszukiwania Olostepem stało się koniecznością, co też oznaczało, że nie mogłem w pełni polegać na ekosystemie Qwen, jak planowałem.
Napotkałem też problem przy eksperymentach z DeepSeek Harness. Zadałem proste pytanie o badanie rynku akcji, a przepływ długo mielił zapytanie, po czym zwrócił błąd. To frustrujące przy tak prostym zadaniu.
Ogólnie Qwen4-Max ma imponujące możliwości, ale jego narzut na rozumowanie i niespójne natywne wyszukiwanie warto rozważyć, zanim zbudujesz na nim produkcyjne przepływy. Jeśli chcesz dalej budować na modelach Qwen, nasz samouczek API Qwen 3.7 Max prowadzi przez agenta produktywności z samorecenzją.
Czy zdarzyło ci się dostać pismo „od rządu” i zastanawiać się, czy jest prawdziwe, czy musisz odpowiadać, czy może ktoś próbuje cię oszukać?
Pisma urzędowe są trudne w lekturze, zwłaszcza gdy zawiły język miesza się z żądaniami płatności i terminami. Oszuści wykorzystują to zamieszanie, podszywając się pod urzędy i wywołując fałszywe poczucie pilności.
W tym samouczku zbudujemy amerykański analizator pism urzędowych z użyciem Qwen4-Max i frameworka Qwen-Agent. Aplikacja przyjmuje tekst, obrazy i PDF-y, oznacza podejrzane taktyki płatnicze oraz przeszukuje oficjalne źródła prawne, gdy trzeba coś zweryfikować.
Zamiast polegać wyłącznie na dużym modelu językowym (LLM), połączymy go z dwoma narzędziami w Pythonie. Pierwsze używa wyrażeń regularnych do wykrywania typowych oznak oszustwa. Drugie korzysta z Olostep do przeszukiwania oficjalnych stron rządowych i Cornell Legal Information Institute (LII).
W skrócie
Czym jest Qwen4-Max?
Qwen4-Max to flagowy model Alibaby z rodziny Qwen4, wprowadzony 16 listopada 2026 r. To rzadki model mixture-of-experts (MoE) z ulepszeniami architektury, natywną wizją i większym kontekstem, zaprojektowany do złożonego rozumowania i aplikacji agentskich.
Najważniejsze cechy dla naszego projektu:
Oto wyniki benchmarków z ogłoszenia Alibaby, pokazujące, że Qwen4-Max poprawia wyniki Qwen3.8-Max w niemal każdej ocenianej kategorii:
Rysunek 1: Wyniki benchmarków Qwen4-Max. Źródło: Qwen, Qwen4-Max: Your New Teammate Has Arrived.
Jak działa analizator pism urzędowych?
Analizator to pojedynczy asystent Qwen-Agent, który koordynuje dwa narzędzia w Pythonie, a Qwen4-Max odpowiada za rozumienie dokumentów i wnioskowanie. Zanim napiszemy kod, spójrzmy na przepływ pracy.
Rysunek 2: Przepływ pracy analizatora pism.
Przepływ ma 6 kroków:
risk_gate, by sprawdzić podejrzane instrukcje płatności, groźby i linki.lookup_law, aby przeszukać oficjalne źródła prawne.Kluczowa decyzja projektowa: LLM nie robi wszystkiego. Python obsługuje deterministyczne sprawdzenia, Olostep – badania zewnętrzne, a Qwen4-Max – rozumienie dokumentu i wnioskowanie.
To utrzymuje prostotę, a jednocześnie daje agentowi odpowiednie narzędzia do każdej części zadania. Jeśli terminologia agentska jest ci nowa, nasz kurs Introduction to AI Agents omawia podstawy bez kodowania.
1. Przygotowanie środowiska
Użyjemy Jupyter Notebook, QwenCloud do dostępu do modelu i Olostep do wyszukiwania i scrapowania sieci.
Najpierw utwórz konto w QwenCloud, doładuj środki lub wykup Token Plan i wygeneruj klucz API w panelu. QwenCloud udostępnia endpoint API na podstawie wybranego regionu.
Będziesz też potrzebować klucza API Olostep do badań prawnych.
Ustaw zmienne środowiskowe w terminalu przed uruchomieniem Jupyter Notebook. Możesz też ustawić je w notebooku przez
os.environ.Używam endpointu Token Plan, który daje tańszy dostęp do modeli. Jeśli płacisz w modelu PAYG, użyj endpointu pokazywanego przez QwenCloud dla twojego regionu.
Następnie zainstaluj wymagane zależności w notebooku:
Dodatek
raginstaluje pakiety do przetwarzania dokumentów, takie jak pdfplumber, którego użyjemy do odczytu PDF-ów. Od wersji 0.0.34 Qwen-Agent importuje też soundfile i tqdm przy starcie bez deklarowania ich jako zależności, więc instalujemy je jawnie.Konfiguracja Qwen4-Max
Teraz inicjalizujemy model i klienta Olostep. Używam regionu Singapur, który również oferuje Token Plan.
To konfiguruje Qwen4-Max dla wejścia multimodalnego, ustawia poziom wysiłku rozumowania i inicjalizuje klienta badań. Zauważ, że
OLOSTEP_API_TIMEOUTustawiamy przed importem, bo SDK odczytuje to przy ładowaniu.Warto znać kilka opcji konfiguracyjnych:
modelokreśla model, którego chcemy użyć.model_typepozwala wysyłać obrazy przez interfejs multimodalny zgodny z OpenAI.model_serverwskazuje endpoint zQWEN_BASE_URL.max_tokensogranicza długość generowanej odpowiedzi.reasoning_effortkontroluje ilość rozumowania modelu. Używamylow, by utrzymać szybkość.OLOSTEP_API_TIMEOUTustawia limit czasu (s) na zapytania badawcze.Tworzenie pomocników agenta do ponownego użycia
Będziemy przetwarzać zarówno tekst, jak i obrazy, więc stwórzmy funkcję do uruchamiania agenta.
Funkcja wysyła prompt i opcjonalne obrazy do Qwen-Agent, czeka na odpowiedź końcową i wyodrębnia wygenerowany tekst.
Potrzebujemy też pomocnika do odczytu PDF-ów.
Funkcja wyciąga zaznaczalny tekst z każdej strony PDF i łączy go w jeden ciąg.
Uwaga: pdfplumber nie wykonuje OCR. Dla skanowanych PDF-ów zawierających tylko obrazy wyrenderuj każdą stronę jako obraz i wyślij bezpośrednio do Qwen4-Max.
2. Wykrywanie oszustw bramką ryzyka
Pierwsze narzędzie wykrywa podejrzane zachowania. Zamiast prosić LLM o rozpoznanie każdej podejrzanej instrukcji płatności, użyjemy wyrażeń regularnych do wykrywania znanych taktyk.
To szybsze, deterministyczne i nie zużywa tokenów modelu. Jeśli chcesz odświeżyć składnię, zajrzyj do naszego kursu Regular Expressions in Python.
Definiowanie reguł wykrywania oszustw
Zacznijmy od listy wyrażeń regularnych i mapowania między agencjami rządowymi a ich oficjalnymi domenami.
Ten kod definiuje wskaźniki oszustw i mapuje nazwy agencji na domeny, których naprawdę używają. Np. jeśli pismo wspomina IRS, aplikacja sprawdza linki względem irs.gov.
Wyodrębnianie i weryfikacja domen
Potrzebujemy teraz pomocnika do wyodrębniania hosta z URL-a.
To wyciąga nazwę hosta i sprawdza, czy to oficjalna domena lub legalna subdomena. To ważne rozróżnienie: proste
endswith()zaakceptowałoby fakeirs.gov jako stronę IRS.Implementacja narzędzia bramki ryzyka
Teraz możemy połączyć te reguły w niestandardowe narzędzie Qwen-Agent.
Narzędzie skanuje pismo pod kątem dopasowań, sprawdza jego URL-e względem oficjalnej domeny agencji i zwraca podejrzane wskaźniki. Nazwy agencji są dopasowywane jako całe słowa, więc „irs” nie zadziała na słowie „first”.
Na przykład nasz fikcyjny list IRS z Testu 1 daje:
Agent otrzymuje te wyniki w swoim kontekście i wykorzystuje je przy ocenie, czy pismo jest podejrzane.
3. Tworzenie narzędzia do badań prawnych
Drugie narzędzie obsługuje badania zewnętrzne. Nie chcemy, by agent przeszukiwał losowe strony, fora czy blogi kancelarii i traktował wszystko jak autorytatywne.
Zamiast tego ograniczamy badania do oficjalnych stron rządu USA i Cornell LII. Użyjemy Olostep, bo potrafi wyszukać i zeskrobać wiele wyników w jednym żądaniu. Jeśli chcesz porównać z inną opcją, zobacz nasz samouczek Firecrawl.
Definiowanie ograniczeń badań
Najpierw określmy dozwolone źródła i limity tego, co pobieramy.
Funkcja
is_allowed_host()akceptuje strony .gov i Cornell LII. Wykorzystujeis_official_domain(), więc sobowtóry typu fakelaw.cornell.edu są odrzucane. Zachowujemy co najwyżej 2 strony, maks. 3000 znaków na stronę.Implementacja narzędzia LookupLaw
Teraz stwórzmy drugie narzędzie niestandardowe.
Narzędzie wysyła zapytanie do Olostep, filtruje wyniki, wyciąga treści stron i zwraca wybrane fragmenty do Qwen4-Max.
Warte uwagi szczegóły implementacyjne:
self.sources, by aplikacja mogła je wyświetlić po analizie.4. Budowa agenta z Qwen-Agent i Qwen4-Max
Mamy już oba narzędzia:
risk_gateidentyfikuje podejrzane zachowania, alookup_lawpobiera istotne informacje prawne. Teraz tworzymy agenta, który je koordynuje.Pojedynczy prompt systemowy definiuje przepływ pracy, kolejność narzędzi i format odpowiedzi. Qwen-Agent nie jest jedyną opcją dla takiej budowy – nasz kurs Developing LLM Applications with LangChain omawia inny framework.
Definiowanie promptu systemowego
Ten prompt definiuje obowiązki agenta i powstrzymuje go przed wymyślaniem informacji prawnych. Jedna wskazówka wymaga uwagi: terminy.
Fałszywe pismo może zawierać termin, więc agent musi podać, co dokument twierdzi, a zarazem wyjaśnić, czy ten termin jest wiarygodny.
Dodanie zastrzeżenia i obsługi źródeł
Trzymamy zastrzeżenie poza promptem systemowym, aby Python mógł je spójnie dodawać.
To daje wiadomość awaryjną, gdy badania nie zwrócą oficjalnego źródła, a każda odpowiedź ma zastrzeżenie prawne.
Tworzenie głównej funkcji analizy
Na koniec połączmy wszystko w jedną funkcję wielokrotnego użytku.
Funkcja tworzy świeżego agenta dla każdego dokumentu, uruchamia analizę, zbiera pobrane źródła i zwraca finalną odpowiedź. Tworzymy
LookupLaw()wewnątrz funkcji, by każde pismo miało własną listę źródeł.5. Testowanie analizatora pism
Mamy już działający analizator pism. Przetestujmy go na 3 przykładach:
Każdy test sprawdza inny element przepływu.
Test 1: List‑oszustwo IRS
Pierwszy przykład to fikcyjny list‑oszustwo IRS. Twierdzi, że odbiorca ma 4 870 USD zaległości w podatku dochodowym i musi zapłacić w ciągu 24 godzin.
Grozi też aresztem, żąda płatności kartami podarunkowymi lub przelewem i zawiera podejrzaną stronę. Oto wejście przykładowe:
To tworzy fikcyjne pismo i przekazuje je agentowi do analizy.
Wynik:
Rysunek 3: Wynik analizatora dla fikcyjnego listu‑oszustwa IRS.
Skaner znajduje kilka podejrzanych wskaźników, a agent pomija badania zewnętrzne. Tego oczekujemy przy oczywistym oszustwie: aplikacja nie wydaje dodatkowych tokenów na badania, gdy deterministyczne sprawdzenia już wskazują na fałsz.
Co pokazuje test: Bramka ryzyka potrafi wykrywać typowe taktyki oszustów i pomaga agentowi unikać zbędnych badań zewnętrznych.
Test 2: Fotografia nakazu eksmisji
Drugi test koncentruje się na natywnej wizji Qwen4-Max. Zamiast samodzielnie wyciągać tekst, wysyłamy bezpośrednio fotografię nakazu eksmisji do modelu.
Nasz przykład to 3‑dniowe zawiadomienie z Florydy z żądaniem 1 850 USD zaległego czynszu lub wydania nieruchomości do 23 listopada 2026 r. Oto kod:
To wysyła fotografię prosto do Qwen4-Max, więc nie potrzeba osobnej ścieżki OCR. Inny projekt łączący wizję Qwen z wywołaniem narzędzi znajdziesz w naszym samouczku API Qwen 3.6 Plus o przetwarzaniu faktur.
Wynik:
Rysunek 4: Wynik analizatora dla sfotografowanego nakazu eksmisji.
Model zrozumiał fotografię, wyciągnął kwotę i termin oraz rozpoznał typ pisma. Zaznaczył, że pobrana strona prawna nie zawierała wystarczających informacji do weryfikacji przepisu i zauważył puste pola podpisu oraz doręczenia w przykładzie.
Co pokazuje test: Qwen4-Max potrafi bezpośrednio interpretować sfotografowane dokumenty prawne, a Qwen-Agent koordynuje dodatkowe badania i komunikuje niepewność.
Test 3: PDF z wezwaniem do zaniechania naruszeń
W ostatnim teście używamy dwustronicowego pisma „cease and desist” w PDF.
Dokument cytuje 17 U.S.C. §§ 501 i 512, zarzuca naruszenie praw autorskich i prosi o usunięcie spornych treści oraz potwierdzenie do 28 listopada 2026 r. PDF zawiera zaznaczalny tekst, więc możemy użyć pomocnika
read_pdf(). Oto kod:To wyciąga zawartość PDF i wysyła tekst do tego samego agenta.
Wynik:
Rysunek 5: Wynik analizatora dla pisma „cease and desist”.
Agent trafnie odróżnia prywatne żądanie prawne od oficjalnego pisma urzędu lub sądu. Rozpoznaje, że nie ma żądania pieniędzy, i dostosowuje rekomendacje. Narzędzie badawcze pobrało odpowiednią stronę US Copyright Office, która pojawia się w źródłach.
Co pokazuje test: Ten sam agent potrafi obsłużyć korespondencję PDF, zidentyfikować charakter żądania prawnego i zaproponować odpowiednie kolejne kroki.
Moje doświadczenia z Qwen4-Max: plusy, minusy i zgrzyty
Po użyciu Qwen4-Max w tym projekcie, innych aplikacjach agentskich i „vibe codingu”, oto moja szczera ocena.
Plusy
Ekosystem Qwen obejmuje wiele obszarów. Oferuje rozpoznawanie mowy, syntezę mowy, wyszukiwanie w sieci, scrapowanie oraz otwarte narzędzia do budowy aplikacji agentskich bez zaczynania od zera.
Najbardziej podobało mi się, jak dobrze Qwen4-Max stosował się do szczegółowych instrukcji. Zwykle respektował żądany format wyjścia, wyciągał daty z dokumentów i tworzył trafne podsumowania w moich testach.
Wyróżniało się rozumienie obrazów. Podałem mu fotografię pisma i odczytał treść bez dodatkowego OCR, co bardzo pomaga w aplikacjach agentskich pracujących z dokumentami.
Minusy
Prędkość była dla mnie największym problemem. Qwen4-Max nie był moim wyborem do „vibe codingu”: w porównaniu z DeepSeek V4.1 Flash i innymi testowanymi modelami często zauważalnie dłużej kończył proste zadania.
Regularnie widziałem tempo generacji ok. 100 tokenów/s, ale to ukrywa realny koszt. Model długo rozumował nad prostymi zmianami, a czasem prosiłem o drobną edycję i czekałem znacznie dłużej niż oczekiwałem.
Jeśli chcesz sam przetestować szybszą opcję, omawiamy ją w samouczku API DeepSeek V4.1 Flash.
Zgrzyty
Najbardziej frustrujące było natywne wyszukiwanie w sieci. W moich testach czasy odpowiedzi były niespójne: to samo zapytanie wracało w sekundy albo trwało prawie minutę, a niektóre żądania przekraczały 400 s i nie kończyły się.
Trzy uruchomienia mojego przepływu badań zajęły prawie 16 minut. To za mało niezawodne dla aplikacji, która polega na zewnętrznych informacjach prawnych.
Zastąpienie natywnego wyszukiwania Olostepem stało się koniecznością, co też oznaczało, że nie mogłem w pełni polegać na ekosystemie Qwen, jak planowałem.
Napotkałem też problem przy eksperymentach z DeepSeek Harness. Zadałem proste pytanie o badanie rynku akcji, a przepływ długo mielił zapytanie, po czym zwrócił błąd. To frustrujące przy tak prostym zadaniu.
Ogólnie Qwen4-Max ma imponujące możliwości, ale jego narzut na rozumowanie i niespójne natywne wyszukiwanie warto rozważyć, zanim zbudujesz na nim produkcyjne przepływy. Jeśli chcesz dalej budować na modelach Qwen, nasz samouczek API Qwen 3.7 Max prowadzi przez agenta produktywności z samorecenzją.