Description

n8n-nodes-upstage

Upstage Solar LLM and Embeddings nodes for n8n workflow automation. This package provides powerful AI capabilities including chat completions, embeddings generation, and document processing through n8n's visual workflow interface.

Features

• Solar Chat Models: Use Upstage's Solar LLM (solar-mini, solar-pro, solar-pro2) for chat completions
• Embeddings Generation: Create high-quality embeddings for semantic search and vector databases
• Document Processing: Parse, OCR, classify, and extract information from documents
• LangChain Integration: Compatible nodes for advanced AI agent workflows
• Secure Authentication: Simple API key-based authentication
• Batch Processing: Efficient batch processing for embeddings and document operations
• Flexible Input: Support for single text, batch processing, binary files, and URLs

Installation

Prerequisites

• n8n: Version 1.0.0 or later
• Node.js: Version 18.0.0 or later

Install via n8n UI (Recommended)

1. Enable Community Nodes (if not already enabled):

   export N8N_COMMUNITY_NODES_ENABLED=true
   n8n start
   

2. Install via n8n UI:

   • Open n8n in your browser
   • Navigate to Settings → Community Nodes
   • Click Install a community node
   • Enter: n8n-nodes-upstage
   • Click Install

Install via npm (Alternative)

npm install n8n-nodes-upstage

Then enable community nodes and restart n8n:

export N8N_COMMUNITY_NODES_ENABLED=true
n8n start

Quick Start

1. Get Your API Key

1. Sign up at Upstage Console
2. Navigate to API Keys section
3. Create a new API key
4. Copy your API key

2. Configure Credentials in n8n

1. In n8n, go to Credentials → Create New
2. Search for "Upstage API"
3. Enter your API key
4. Click Test to verify the connection
5. Click Save

3. Use the Nodes

1. Create a new workflow in n8n
2. Click Add Node and search for "Upstage"
3. Select any Upstage node (e.g., "Upstage Solar Chat")
4. Configure the node with your credentials
5. Set up your workflow and execute!

Available Nodes

Basic Nodes

Upstage Solar Chat (LmChatUpstage)

Use Upstage Solar LLM models for chat completions with conversation support.

Supported Models:

• solar-mini – Fast and efficient for basic tasks
• solar-pro – Powerful model for complex tasks
• solar-pro2 – Latest and most advanced Solar model with JSON support

Key Features:

• Message-based conversation format (system, user, assistant roles)
• Configurable parameters: temperature, max tokens, top-p
• Streaming response support
• Response format options (solar-pro2 only):
  • Text (default)
  • JSON Object – Generate structured JSON responses
  • JSON Schema – Generate JSON with custom schema for structured outputs
• Reasoning effort control
• Frequency and presence penalty
• Function calling support (tools)

Example Use Cases:

• Customer support chatbots
• Content generation
• Code generation and explanation
• Data extraction and analysis

Upstage Embed (EmbeddingsUpstage)

Generate high-quality embeddings using Solar embedding models for semantic search and similarity matching.

Supported Models:

• embedding-query – Optimized for search queries and questions
• embedding-passage – Optimized for documents and passages

Key Features:

• Single text or batch processing (up to 100 texts per request)
• Input from node parameters or previous node data
• High-dimensional vector outputs
• Token limits: Max 204,800 total tokens, 4,000 per text (optimal: under 512)

Example Use Cases:

• Semantic search
• Document similarity matching
• Clustering and classification
• Recommendation systems

Upstage Document Parse (DocumentParsingUpstage)

Convert documents into structured HTML/Markdown format with layout preservation.

Supported Models:

• document-parse – Recommended stable model
• document-parse-nightly – Latest experimental features

Key Features:

• Sync and async document processing
• Multiple output formats (HTML, Markdown, Text)
• OCR support with auto/force modes
• Chart recognition and table merging
• Base64 encoding for figures, tables, equations, charts
• Coordinate information inclusion

Supported Formats:

• Images: JPEG, PNG, BMP, TIFF, HEIC
• Documents: PDF, DOCX, PPTX, XLSX

Example Use Cases:

• Document digitization
• Content extraction from PDFs
• Table extraction and conversion
• Document structure analysis

Upstage Document OCR (DocumentOCRUpstage)

Extract text from document images and PDFs with high accuracy.

Supported Models:

• ocr – Recommended (always points to latest stable)
• ocr-250904 – Specific version

Key Features:

• Multiple OCR models
• Schema options (Upstage, Clova, Google)
• Page-level text extraction
• Confidence scores
• Multiple return modes (full, text, pages, words, confidence)

Supported Formats:

• Images: JPEG, PNG, BMP, TIFF, HEIC
• Documents: PDF, DOCX, PPTX, XLSX, HWP, HWPX

Example Use Cases:

• Text extraction from scanned documents
• Invoice and receipt processing
• Form data extraction
• Multi-language OCR

Upstage Information Extract (InformationExtractionUpstage)

Extract structured information from documents using custom JSON schemas.

Supported Models:

• information-extract – Recommended

Key Features:

• Custom JSON schema definition
• Form-based or raw JSON schema input
• Support for nested structures
• Schema generation mode
• Binary file or URL input

Example Use Cases:

• Invoice data extraction
• Resume parsing
• Contract analysis
• Form data extraction

Upstage Document Classify (DocumentClassificationUpstage)

Classify documents into predefined categories with confidence scores.

Supported Models:

• document-classify – Document classification model

Key Features:

• Custom category definitions
• Binary file or URL input
• Form-based or JSON schema input
• Confidence scores for classifications

Example Use Cases:

• Document type classification
• Spam detection
• Content categorization
• Quality control

LangChain-Compatible Nodes (AI Agent Workflows)

Upstage Solar Chat for Agent (LmChatModelUpstage)

LangChain-compatible chat model for use with n8n AI Chain and AI Agent nodes.

Key Features:

• Automatic model selection from API
• Token usage tracking
• Streaming support
• Response format options (solar-pro2 only):
  • Text (default)
  • JSON Object – Generate structured JSON responses
  • JSON Schema – Generate JSON with custom schema for structured outputs
• Function calling support (tools) – Bind tools to the model using LangChain bindTools
• N8n tracing integration
• Proxy support

Connections:

• Connects to: AI Chain, AI Agent nodes
• Output: Language Model

Example Use Cases:

• AI agent workflows
• Multi-step reasoning
• Tool-using agents
• Complex AI chains

Upstage Embed for Agent (EmbeddingsUpstageModel)

LangChain-compatible embeddings model for vector databases and AI agent workflows.

Key Features:

• LangChain Embeddings interface
• Batch processing support
• Vector database integration
• Automatic text preprocessing

Connections:

• Connects to: AI Vector Store nodes
• Output: Embeddings

Example Use Cases:

• RAG (Retrieval-Augmented Generation) workflows
• Vector database population
• Semantic search in AI agents
• Document similarity in agents

Usage Examples

Simple Chat Completion

1. Add Upstage Solar Chat node
2. Configure with your Upstage API credentials
3. Set model to solar-mini
4. Add a message with role "user" and your prompt
5. Execute to get AI response

Text Embeddings

1. Add Upstage Embed node
2. Configure credentials
3. Choose appropriate model (query vs passage)
4. Input your text
5. Get embedding vectors for similarity search, clustering, etc.

Batch Processing

Use the Upstage Embed node with "Array of Texts" input type to process multiple texts efficiently in a single API call.

Document Parsing Workflow

1. Read Binary File node → Read PDF
2. Upstage Document Parse node → Parse to Markdown
3. Process the structured output

AI Agent with LangChain

1. Upstage Solar Chat for Agent → Configure model
2. AI Agent node → Connect to chat model
3. Upstage Embed for Agent → Connect to vector store
4. Build complex AI workflows

Structured JSON Output (Response Format)

Use response format options to get structured JSON responses from the model:

1. Add Upstage Solar Chat or Upstage Solar Chat for Agent node
2. Select solar-pro2 model
3. In Options, set Response Format to:
   • JSON Object: For simple JSON responses (requires "JSON" in prompt)
   • JSON Schema: For custom structured outputs with your own schema
4. If using JSON Schema, provide your JSON schema definition
5. Execute to get structured JSON response

Example JSON Schema:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" },
    "email": { "type": "string" }
  },
  "required": ["name", "email"]
}

Configuration

API Endpoints

• Chat: https://api.upstage.ai/v1/chat/completions
• Embeddings: https://api.upstage.ai/v1/embeddings
• Document Parsing: https://api.upstage.ai/v1/document-digitization
• Document OCR: https://api.upstage.ai/v1/ocr
• Information Extraction: https://api.upstage.ai/v1/information-extraction
• Document Classification: https://api.upstage.ai/v1/document-classify

Rate Limits

Please refer to Upstage API Documentation for current rate limits and usage guidelines.

Model Limits

• Embeddings:
  • Max 100 strings per request
  • Max 204,800 total tokens per request
  • Max 4,000 tokens per text (optimal: under 512 tokens)
• Chat:
  • Max tokens vary by model (check model documentation)
  • Context windows: 2,048 to 32,768 tokens depending on model

API Reference

• Upstage Chat API Documentation
• Upstage Embeddings API Documentation
• Upstage Document APIs Documentation
• n8n Community Nodes Documentation

Troubleshooting

Node Not Visible

1. Verify community nodes are enabled: N8N_COMMUNITY_NODES_ENABLED=true
2. Restart n8n completely
3. Clear browser cache
4. Check n8n logs for installation errors
5. Verify the package is properly installed: npm list n8n-nodes-upstage

API Errors

1. Invalid API Key: Verify your API key is correct and active
2. Rate Limit: Check if you've exceeded API rate limits
3. Network Issues: Verify network connectivity to api.upstage.ai
4. Model Availability: Ensure the selected model is available in your region

Common Issues

Error: "At least one message is required"

• Ensure you've added at least one message in the chat node

Error: "No input text provided"

• Check that text input is not empty
• Verify the text field name matches your input data

Error: "Invalid JSON schema"

• Validate your JSON schema syntax
• Ensure the schema follows the required format

Document Processing Fails

• Verify the file format is supported
• Check file size limits
• Ensure binary property name is correct

Development

Building from Source

# Clone the repository
git clone https://github.com/UpstageAI/n8n-nodes-upstage.git
cd n8n-nodes-upstage

# Install dependencies
npm install

# Build the project
npm run build

# Run in watch mode
npm run dev

Testing Locally

# Build and create npm link
npm run build
npm link

# In your n8n installation directory
cd /path/to/n8n
npm link n8n-nodes-upstage --legacy-peer-deps

# Start n8n with community nodes enabled
N8N_COMMUNITY_NODES_ENABLED=true n8n start

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License – see LICENSE file for details.

Links

• Upstage Console
• Upstage Documentation
• Solar LLM Documentation
• n8n Documentation
• n8n Community Nodes
• GitHub Repository
• Report Issues

Acknowledgments

• Built with n8n workflow automation platform
• Powered by Upstage Solar AI models
• Uses LangChain for AI agent integration

Made with ❤️ by Upstage