اتصال n8n به هوشوانا

n8n ابزار ساخت گردش‌کار و اتوماسیون است. نودهای هوش مصنوعی آن از credential نوع OpenAI استفاده می‌کنند و این credential فیلد Base URL دارد. با گذاشتن آدرس هوشوانا در این فیلد، همه‌ی نودهای مبتنی بر OpenAI به هوشوانا وصل می‌شوند.

چه چیزی به دست می‌آورید

• استفاده از مدل‌های چند سازنده در نودهای OpenAI Chat Model و AI Agent.
• پرس‌وجو از پایگاه دانش هوشوانا داخل گردش‌کار.
• پرداخت ریالی و گزارش هزینه‌ی هر اجرای گردش‌کار.

پیش‌نیازها

1. حساب کاربری در هوشوانا.
2. یک کلید API از صفحه‌ی کلیدها.
3. اعتبار کافی در کیف پول.
4. n8n نسخه‌ی جدید (ابری یا روی سرور خودتان).

راه‌اندازی

۱. ساخت credential

1. در n8n به Credentials بروید و Create credential را بزنید.
2. نوع OpenAI را انتخاب کنید.
3. فیلدها را پر کنید:

4. ذخیره کنید. n8n اتصال را آزمایش می‌کند و باید پیام موفقیت ببینید.

۲. نود OpenAI Chat Model با AI Agent

1. یک گردش‌کار تازه بسازید و نود Chat Trigger (یا هر تریگر دیگر) را اضافه کنید.
2. نود AI Agent را بعد از تریگر بگذارید.
3. در ورودی Chat Model نود AI Agent، نود OpenAI Chat Model را وصل کنید.
4. در OpenAI Chat Model، credential هوشوانا را انتخاب کنید.
5. در فیلد Model، اگر فهرست مدل‌ها بارگذاری شد مدل را از فهرست انتخاب کنید؛ وگرنه حالت By ID را بزنید و شناسه را بنویسید، مثلاً openai/gpt-4o-mini.
6. در صورت نیاز، نود Memory و ابزارها (Tools) را هم به AI Agent وصل کنید.

نود OpenAI Chat Model را می‌توانید به زنجیره‌های دیگر مثل Basic LLM Chain و Summarization Chain هم وصل کنید. نود Embeddings OpenAI هم با همین credential و مدل openai/text-embedding-3-small کار می‌کند.

۳. پرس‌وجو از پایگاه دانش با HTTP Request

اگر در هوشوانا پایگاه دانش ساخته‌اید، می‌توانید بدون vector store جداگانه، مستقیم از آن جست‌وجو کنید:

1. نود HTTP Request را اضافه کنید.
2. Method را POST بگذارید.
3. URL را این‌طور بنویسید (شناسه‌ی پایگاه دانش را از داشبورد بردارید):

https://hooshvana.ir/api/v1/kb/kb_YOUR_ID/query

4. در Authentication گزینه‌ی Generic Credential Type و بعد Header Auth را انتخاب کنید. نام هدر Authorization و مقدار آن Bearer hv-YOUR_KEY باشد.
5. Send Body را روشن کنید، نوع را JSON بگذارید و بدنه را بنویسید:

{
  "query": "{{ $json.chatInput }}",
  "top_k": 5
}

عبارت {{ $json.chatInput }} یک expression در n8n است و متن پیام کاربر را از Chat Trigger می‌گیرد. پاسخ شامل تکه‌های مرتبط با امتیاز شباهت و عنوان و آدرس منبع است و می‌توانید آن را به نود بعدی، مثلاً یک Basic LLM Chain، بدهید.

بررسی اتصال

1. در گردش‌کار AI Agent روی Open chat بزنید و یک پیام بفرستید.
2. اگر پاسخ آمد، اتصال درست است.
3. در گزارش‌ها درخواست‌های /chat/completions و در صورت استفاده، /kb/.../query را ببینید.

مدل‌های پیشنهادی

برای AI Agentی که ابزار صدا می‌زند، مدلی انتخاب کنید که function calling را پشتیبانی کند. شناسه‌ها نمونه هستند؛ فهرست کامل در کاتالوگ مدل‌ها است.

کنترل هزینه

گردش‌کارهای زمان‌بندی‌شده و وب‌هوک‌ها ممکن است بدون اینکه متوجه شوید بارها اجرا شوند.

• برای هر گردش‌کار مهم یک کلید جدا بسازید تا هزینه‌ها از هم جدا باشند.
• سقف خرج روزانه بگذارید تا یک حلقه‌ی اشتباه هزینه‌ی زیادی نسازد.
• مدل‌های مجاز را به مدل‌هایی که در گردش‌کار استفاده می‌کنید محدود کنید.
• اگر n8n روی سرور خودتان است، IP سرور را در فهرست IP مجاز کلید بگذارید.
• با سقف توکن در هر درخواست طول پاسخ‌ها را کنترل کنید.

رفع اشکال

اگر مشکل ادامه داشت، کد خطا و زمان درخواست را در تیکت پشتیبانی بفرستید.